Content
# A2A Agents
This project demonstrates a multi-agent system using **LangGraph**, exposed via the **[Agent2Agent (A2A) Protocol](https://a2a-protocol.org/)** and accessible through **[Chainlit](https://chainlit.io/)** UIs.
It showcases how independent agents can communicate and collaborate: a **Conversation Agent** can dynamically discover and utilize the skills of a **Math Agent** running as a separate service.
## Features
- **Math Agent**: A specialized agent capable of solving arithmetic problems. It exposes its capabilities via the A2A protocol.
- **Conversation Agent**: A general-purpose chat agent that can route math questions to the Math Agent by consuming its A2A "Agent Card".
- **A2A Protocol Integration**: Demonstrates dynamic tool creation from remote agent specifications.
- **Chainlit UI**: Provides user-friendly chat interfaces for both agents.
- **Verification Scripts**: Includes scripts to verify the A2A server and agent-to-agent integration.
## Architecture
```mermaid
graph TD
User[User] -->|Interacts via UI| C_UI["Conversation Agent UI\n(Chainlit)"]
subgraph "Conversation Agent (Client)"
C_UI --> C_App[App Logic]
C_App -->|Uses| C_Graph[LangGraph]
C_Graph -->|Calls| A2A_Client[A2A Client]
end
subgraph "Math Agent (Server)"
A2A_Client -->|HTTP / A2A Protocol| M_Server[A2A Server]
M_Server -->|Executes| M_Graph[Math LangGraph]
M_Graph -->|Solves| M_Logic[Math Logic]
end
C_Graph -.->|LLM Calls| LLM["LLM Provider\n(OpenRouter)"]
M_Graph -.->|LLM Calls| LLM
```
## Prerequisites
- Python 3.12+
- [uv](https://github.com/astral-sh/uv) (recommended for fast dependency management)
## Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd a2a-agents
```
2. Install dependencies:
```bash
uv sync
```
## Configuration
1. Create a `.env` file in the root directory. You can copy `.env.example` if it exists, or use the template below:
```env
# LLM Provider Configuration
OPENROUTER_API_KEY=your_openrouter_api_key
MODEL_NAME=openai/gpt-4o
API_BASE_URL=https://openrouter.ai/api/v1
# Agent Integration Configuration
# URL where the Math Agent (A2A Server) will be running
REMOTE_AGENT_URL=http://localhost:8000
```
## Usage
The system consists of two main parts: the Math Agent (Server) and the Conversation Agent (Client).
### 1. Start the Math Agent (A2A Server)
The Math Agent needs to run as a server to expose its skills.
```bash
# In a new terminal window
uv run -m agents.math_agent.backend.server
```
*This will start the A2A server on `http://localhost:8000`.*
### 2. Run the Conversation Agent
You can interact with the Conversation Agent via Chainlit. It is configured to talk to the Math Agent running at `REMOTE_AGENT_URL`.
```bash
# In a separate terminal window
cd agents/conversation_agent
uv run chainlit run app.py -w
```
*Access the UI at `http://localhost:8001` (or the port shown in the terminal).*
**Try it out:**
Ask the Conversation Agent: *"Calculate 25 * 25"*
It should route this request to the Math Agent and return the result.
### 3. Verification & Testing
The project includes scripts to verify the components independently.
**Verify A2A Server (Probe SDK):**
Check if the Math Agent is correctly exposing its skills.
```bash
uv run probe_sdk.py
```
**Verify Agent-to-Agent Integration:**
Simulate the Conversation Agent calling the Math Agent without the UI.
```bash
uv run verify_a2a.py
```
### 4. Run Math Agent UI (Optional)
You can also talk to the Math Agent directly.
```bash
cd agents/math_agent
uv run chainlit run app.py -w
```
## Project Structure
- `agents/`
- `math_agent/`:
- `backend/server.py`: The A2A server implementation for the Math Agent.
- `backend/agent.py`: The LangGraph logic for math solving.
- `app.py`: Chainlit UI for the Math Agent.
- `conversation_agent/`:
- `app.py`: Chainlit UI and main logic for the Conversation Agent.
- `probe_sdk.py`: A script to test the A2A server connection and message format.
- `verify_a2a.py`: An integration test script for the agent-to-agent flow.
- `pyproject.toml`: Project dependencies.
## Troubleshooting
- **Port Conflicts**: Ensure port 8000 is free for the Math Agent server. If `chainlit` tries to use the same port, it usually auto-increments, but check the terminal output.
- **Connection Refused**: Make sure the Math Agent server is running *before* you start the Conversation Agent or run verification scripts.
- **Missing API Key**: Ensure `OPENROUTER_API_KEY` is set in your `.env` file.
