# Currency Agent

An AI agent implementation built on Google Cloud, featuring **MCP (Model Context Protocol)** for tool integration, **ADK (Agent Development Kit)** for orchestration, and **A2A (Agent-to-Agent)** protocol for inter-agent communication.

---

## Setup & Google Cloud Configuration

### 1. Authenticate & Verify Project

Open the Cloud Shell and verify your active account:

```bash
gcloud auth list
```

Display the active Google Cloud project ID:

```bash
gcloud config list project
```

### 2. Configure Environment Variables

Export your Project ID to an environment variable and configure `gcloud`:

```bash
export PROJECT_ID="<YOUR_PROJECT_ID>"
gcloud config set project $PROJECT_ID
```

### 3. Enable Required Google Cloud APIs

Enable all required Google Cloud service APIs for the project:

```bash
gcloud services enable \
  cloudresourcemanager.googleapis.com \
  servicenetworking.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com
```

---

## Installation & Local Setup

This project requires **Python 3.10+**. Verify your Python version in Cloud Shell:

```bash
python3 --version
```

### 1. Clone the Repository
Clone the repository to your environment:

```bash
git clone https://github.com/jackwotherspoon/currency-agent.git
cd currency-agent
```

### 2. Install Dependency Manager (`uv`)
This project uses `uv` to manage Python dependencies. Install `uv` using the following curl command:

```bash
curl -LsSf https://astral.sh/uv/install.sh | bash
```

To verify the installation in a new terminal, check the version and executable location:

```bash
uv --version
which uv
```

### 3. Configure Environment Variables
Create and configure your `.env` file to supply the necessary variables:

```bash
echo "GOOGLE_GEN_AI_USE_VERTEXAI=True" >> .env \
  && echo "GOOGLE_CLOUD_LOCATION=us-central1" >> .env \
  && echo "GOOGLE_CLOUD_PROJECT=$PROJECT_ID" >> .env
```

Verify that the `.env` file has been populated correctly:

```bash
cat .env
```

---

## Running and Testing the Server Locally

### 1. Start the MCP Server
Run the following command in your Cloud Shell terminal to start the server:

```bash
uv run mcp-server/server.py
```

### 2. Test the MCP Server
Open a new Cloud Shell terminal and run the test script. This will query the server's API and output the result:

```bash
uv run mcp-server/test_server.py
```

---

## Deployment to Google Cloud Run

To make the tool permanent, reliable, and benefit from automatic scaling, deploy the MCP server to Google Cloud Run.

### 1. Deploy the Service
Stop the local server and run the following deployment command from within the `mcp-server` directory:

```bash
gcloud run deploy mcp-server \
  --no-allow-unauthenticated \
  --region=us-central1 \
  --source .
```

> [!IMPORTANT]
> The `--no-allow-unauthenticated` flag is critical for security. It ensures that only authorized accounts can access the deployed server.

### 2. Authenticate and Proxy Deployed Calls
To securely access and test the live Cloud Run service locally, start a local proxy tunnel:

```bash
gcloud run services proxy mcp-server --region=us-central1
```

This establishes a secure tunnel between your local machine (or Cloud Shell) and the Cloud Run service.

![alt text](image.png)

### 3. Test the Deployed Service
With the proxy running, open a new Cloud Shell terminal and run the test script:

```bash
uv run mcp-server/test_server.py
```

### 4. View Deployment Logs
To monitor the service and verify requests, stream the logs from the command line:

```bash
gcloud run services logs read mcp-server --region=us-central1 --limit=5
```

![alt text](image-1.png)

You are now ready to build and run agents interacting with your deployed tools!

---

## External APIs & Data Sources

### Currency Converter Endpoint

The agent utilizes the Frankfurter API for real-time exchange rates:

- **Endpoint**: `https://api.frankfurter.dev/v2/latest`
- **Sample Request**:
  ```http
  GET https://api.frankfurter.dev/v2/latest?base=USD&symbols=INR,EUR
  ```