Content
# A2A Experiment Repository
This repository aims to document and demonstrate the experimental process of Agent development and interaction using the Google Agent Development Kit (ADK) and the Agent-to-Agent (A2A) protocol.
## Experiment Objectives
Through practical operations, we aim to gain a deeper understanding of the A2A protocol's working principles, experience the development process of Google ADK, and explore the possibilities of integrating custom large language models (such as the Volcengine deepseek model used in this experiment, integrated via LiteLLM) into the A2A ecosystem.
## Experimental Environment and Steps
### 1. Basic Setup
- Clone the official Google A2A repository: `git clone https://github.com/google/A2A.git`
- Create a separate experiment directory (e.g., `A2A_exp`).
- Copy the official repository's `samples/python/agents/google_adk` and `samples/python/common` directories to the experiment directory.
- Copy the official repository's `samples/python/hosts/cli` directory to the experiment directory.
- Copy the official repository's `samples/python/hosts/multiagent/ui` directory to the experiment directory.
### 2. Python Environment (using uv)
Initialize and activate the virtual environment in the root directory of `A2A_exp`:
```bash
uv init
uv venv
.venv/Scripts/activate
```
### 3. Agent (`google_adk`) Configuration and Running
- **Install Dependencies:**
```bash
# Navigate to the google_adk directory
cd google_adk
# Install ADK and LiteLLM
uv pip install google-adk litellm python-dotenv # Add dotenv for loading .env
```
*Note:* It was found that directly installing the `google-adk` package may not resolve the import issue for the `common` package, so the `common` directory needs to be manually copied to the project root directory and declared in `pyproject.toml`.
- **Modify `pyproject.toml` (in the root directory of `A2A_exp`):**
Ensure that the `[tool.setuptools]` or similar section includes `common`, `google_adk`, etc. (If you initialized with `uv init`, manual modification may not be necessary, but ensure uv can find these packages)
```toml
[project]
name = "a2a-exp"
version = "0.1.0"
description = "A2A Experimentation Repository"
readme = "README.md"
requires-python = ">=3.10" # Adjust according to actual situation
dependencies = [
"google-adk",
"litellm",
"python-dotenv",
# Add other dependencies required by cli and ui
"jwcrypto",
"PyJWT",
"asyncclick",
"fastapi",
"httpx",
"httpx-sse",
"mesop",
"pandas",
"pydantic",
"uvicorn",
"ruff"
]
[tool.uv.sources]
# If needed, specify pypi source
# default = "https://pypi.tuna.tsinghua.edu.cn/simple"
# Ensure uv can find local packages
# (uv usually auto-discovers sibling directories, or may require more complex configuration)
# If issues arise, consider adding common, google_adk, etc. as path dependencies
```
- **Configure Agent to Use LiteLLM:**
- Modify `google_adk/agent.py`:
- Import `LiteLlm`: `from google.adk.models.lite_llm import LiteLlm`
- Import `load_dotenv`: `from dotenv import load_dotenv`
- Load environment variables at the beginning of the script: `load_dotenv()`
- Modify the `_build_agent` method to point the `model` parameter to the `LiteLlm` instance and specify the model name (e.g., Volcengine model).
```python
from google.adk.models.lite_llm import LiteLlm
from dotenv import load_dotenv
load_dotenv() # Load .env file
# ... other imports ...
class ReimbursementAgent(Agent):
# ... other methods ...
def _build_agent(self) -> LlmAgent:
"""Builds the LLM agent for the reimbursement agent."""
return LlmAgent(
model=LiteLlm(model="volcengine/ep-xxxxxxxxxxxx-xxxxx"), # Replace with your model endpoint ID
name="reimbursement_agent",
description=(
"This agent handles the reimbursement process for the employees"
" given the amount and purpose of the reimbursement."
),
)
# ... other methods ...
```
- Create a `.env` file in the `google_adk` directory and add the API key:
```
VOLCENGINE_API_KEY=xxxxxxxxxxxxxxxxx
```
- Add `.env` to the `.gitignore` file.
- **Run the Agent Service:**
```bash
# Ensure you are in the google_adk directory
uv run .
```
The service will listen at `http://localhost:10002` (default).
### 4. Host (CLI) Configuration and Running
- **Install Dependencies:** (Already installed in step 3 via the root directory's `pyproject.toml`)
```bash
# Ensure jwcrypto, PyJWT, asyncclick are installed in the project root
# uv pip install jwcrypto PyJWT asyncclick
```
- **Run CLI Host:**
```bash
# Navigate to the cli directory
cd ../cli
# Run and connect to the Agent service
uv run . --agent http://localhost:10002
```
Follow the prompts to input interaction content with the Agent.
### 5. Host (Web UI) Configuration and Running
- **Install Dependencies:** (Already installed in step 3 via the root directory's `pyproject.toml`)
```bash
# Ensure asyncio, fastapi, httpx, httpx-sse, mesop, pandas, pydantic, uvicorn, ruff are installed in the project root
# uv pip install asyncio fastapi httpx httpx-sse mesop pandas pydantic uvicorn ruff
```
- **Modify Code (if necessary):**
- Check and modify the import paths in `ui/service/server/adk_host_manager.py` and `ui/main.py`, removing any existing `hosts.` prefixes to ensure correct imports from the root directory's `common` and `google_adk`.
- Ensure that `ui/main.py` or its called modules can correctly load environment variables (e.g., also using `dotenv`).
- **Configure UI Environment Variables:**
- Create a `.env` file in the `ui` directory (if needed, e.g., for Google API Key used for Host Agent functionality, but this experiment mainly relies on Remote Agent):
```
GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY # If Host Agent needs Gemini
```
- **Run Web UI Host:**
```bash
# Navigate to the ui directory
cd ../ui
# Run UI service
uv run main.py
```
Access `http://localhost:12000/event_list` (or the address configured in `main.py`).
### 6. Web UI Experiment
- In the Web UI interface, configure "Remote Agents" to point to the running Agent service address (`http://localhost:10002`).
- Enter requests in the chat box, such as "Can you reimburse me $20 for my lunch with the clients?"
- Observe the interaction process:
- The Agent recognizes insufficient information (missing date).
- The Agent returns a form to the Host via the A2A protocol.
- The Web UI Host renders the form.
- The user fills in the date information in the form and submits it.
- The Host sends the form data containing the additional information back to the Agent.
- The Agent completes processing and returns the final confirmation message.
- You can view detailed interaction events and task statuses through the Web UI's "Event List" and "Task List".
## Experiment Conclusions and Reflections
- Google ADK provides a complete framework for Agent development and interaction, enabling collaboration between Agents through the A2A protocol.
- Using the Web UI Host (built with `mesop`) presents the complex features of A2A interactions, such as form data transmission, more intuitively than the CLI Host.
- Integrating custom models (like the Volcengine model) into the ADK Agent via LiteLLM is feasible, enhancing the flexibility of the Agent.
- The A2A protocol involves multi-step communication (retrieving Agent Card, sending requests, handling Function Calling, receiving forms, sending form data, etc.), and even in a local environment, interactions may experience some latency.
- The official sample code may currently have some path dependency issues (such as with the `common` package), requiring manual adjustments or careful attention to project structure and build configuration.
---
*This README is based on a specific A2A experimental process, documenting the environment setup, code modifications, running steps, and encountered issues.*
