Content
# A2A Protocol Demo Implementation 🤖
This is a minimal reference implementation project for the **Agent-to-Agent (A2A)** communication protocol.
The project aims to demonstrate how agents in Multi-Agent Systems can perform **capability discovery**, **task submission**, **streaming state synchronization**, and **result delivery** through standardized interfaces.
> **Learning Objective**: Understand the "Slot" mechanism in MCP (Model Context Protocol) and the A2A protocol, dynamic semantic discovery, and asynchronous task flow.
## 📂 Project Structure
```text
a2a_demo/
├── protocol.py # Core protocol definitions (Pydantic models: AgentCard, Artifact, TaskState)
├── server.py # Server Agent (based on FastAPI, providing RPC and SSE interfaces)
├── client.py # Client invocation script (simulating dynamic discovery and invocation between agents)
├── requirements.txt # Project dependencies
└── README.md # Documentation
```
## 🚀 Quick Start
### 1. Environment Setup
Ensure that Python 3.9+ is installed.
```bash
# It is recommended to create a virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
```
### 2. Run the Project
You need to open two terminal windows to simulate the server and client.
**Terminal 1 (Server):**
Start the Server Agent, listening on port 8000.
```bash
python server.py
# Output: 🚀 Server Agent starting: http://127.0.0.1:8000
```
**Terminal 2 (Client):**
Run the Client script to initiate the A2A invocation process.
```bash
python client.py
```
## 📝 Core Concepts
When you run `client.py`, you will observe four key phases of the A2A protocol:
### 1. 🔍 Capability Discovery (Context Discovery)
* **Action**: Client requests `/.well-known/agent.json`.
* **Concept**: **Dynamic Discovery**.
* The Client does not need to hard-code the Server's capabilities in the code.
* The Client reads the Server's `input_spec` at **runtime**, instantly understanding how to construct the request. This is the foundation of Agent generality.
### 2. 🤝 Handshake and Submission (RPC Invocation)
* **Action**: Client sends `POST /rpc` (JSON-RPC 2.0).
* **Concept**: **Slot Filling**.
* The Client fills in parameters (e.g., `text`) based on the specification just seen.
* The Server returns a `task_id`, rather than returning the result directly (non-blocking design).
### 3. ⏳ State Evolution (Context Evolution)
* **Action**: Client listens to `GET /events/{task_id}` (SSE).
* **Concept**: **Streaming Context**.
* The Server pushes intermediate states of the task via Server-Sent Events (e.g., "Tokenizing..." -> "Analyzing...").
* This enables observability of long-running tasks.
### 4. 🎁 Result Delivery (Artifact Delivery)
* **Action**: Server pushes the final data package.
* **Concept**: **Artifact**.
* The result is encapsulated as a structured object containing `mime_type`, `metadata`, and `data`.
* It is not just a returned string, but an entity that can be consumed by downstream programs.
## 📚 Learning Note: What is "Dynamic Discovery"?
In this project, `client.py` embodies the core idea of the A2A protocol:
* **Static (Hard-coded)**: Programmers write code by looking up documentation and hard-coding parameter names (e.g., `server.call("analyze", text="...")`). If the server interface changes, the client code will break.
* **Dynamic (A2A Mode)**: The client code **does not assume** what capabilities the server has.
1. Connect to the server.
2. Download the "specification" (`AgentCard`).
3. Read the specification on-site.
4. Construct requests based on the specification.
* *Metaphor: You don’t need to memorize the entire menu of every restaurant (hard-coded); you just need to learn to "check the menu first" (dynamic discovery), so you can order at any new restaurant you visit.*
## 🛠️ Tech Stack
* **Python 3.10+**
* **FastAPI**: For building high-performance web services.
* **SSE-Starlette**: For handling streaming responses (Server-Sent Events).
* **Pydantic**: For data model definition and validation (Schema definition).
* **HTTPX**: For asynchronous HTTP client.
## License
MIT
