# A2A Agent-to-Agent 演示项目

A2A 协议（Google）的 Python 演示。对比「有 A2A」和「没有 A2A」两种集成方式。

## 项目结构

```
a2a-demo/
├── server.py                # 问答 Agent（端口 9999）→ A2A Server
├── server_translator.py     # 翻译 Agent（端口 9998）→ A2A Server
├── client.py                # A2A 全流程演示（发现 + 调用 + 跨 Agent 管道）
├── compare.py               # 交互式对比：直连 DeepSeek vs 走 A2A
├── demo_no_a2a.py           # ❌ 无 A2A：两个 Agent 不同 API，手工适配
└── demo_with_a2a.py         # ✅ 有 A2A：同一套协议，零适配代码
```

## 先决条件

Python 3.10+（推荐 3.11），项目自带 uv 虚拟环境。

```bash
cd ~/Desktop/miaoa/AI/projects/a2a-demo
source .venv/bin/activate
```

如果虚拟环境不存在，重建：

```bash
cd ~/Desktop/miaoa/AI/projects/a2a-demo
uv venv --python 3.11
uv pip install a2a-sdk uvicorn starlette openai httpx sse-starlette httpx-sse
```

---

## 一、快速体验：A2A vs 无 A2A 对比

需要 3 个终端。

### 终端 1 — 启动问答 Agent（A2A Server）

```bash
cd ~/Desktop/miaoa/AI/projects/a2a-demo
source .venv/bin/activate
python server.py
```

看到输出：
```
🚀 A2A Server 启动 → http://127.0.0.1:9999
INFO:     Uvicorn running on http://127.0.0.1:9999
```

### 终端 2 — 启动翻译 Agent（A2A Server）

```bash
cd ~/Desktop/miaoa/AI/projects/a2a-demo
source .venv/bin/activate
python server_translator.py
```

看到输出：
```
🌐 翻译 Agent → http://127.0.0.1:9998
INFO:     Uvicorn running on http://127.0.0.1:9998
```

### 终端 3 — 运行对比 Demo

**先看没有 A2A 的情况：**

```bash
cd ~/Desktop/miaoa/AI/projects/a2a-demo
source .venv/bin/activate
python demo_no_a2a.py
```

**再看有 A2A 的情况：**

```bash
python demo_with_a2a.py
```

### 预期效果

```
❌ 没有 A2A
   问答 → 手动写: POST /ask  {"question": ...}
   翻译 → 手动写: POST /v2/translate  {"src": ...}  → 解析 resp.data.result
   第三个 → 再写一套适配代码
   → N 个 Agent = N 套适配代码

✅ 有 A2A
   问答 → call_a2a_agent(url, question)  ← 同一函数
   翻译 → call_a2a_agent(url, question)  ← 同一函数
   第三个 → call_a2a_agent(url, question)  ← 直接复用
   → N 个 Agent = 1 套代码
```

---

## 二、交互式对比测试

一边是直连 DeepSeek API，一边是经过 A2A 协议转发。

**前提**：问答 Agent（server.py）必须在 9999 端口运行。

```bash
# 终端 1：启动 Server
cd ~/Desktop/miaoa/AI/projects/a2a-demo
source .venv/bin/activate
python server.py

# 终端 2：运行对比
cd ~/Desktop/miaoa/AI/projects/a2a-demo
source .venv/bin/activate
python compare.py
```

进入交互模式后，输入问题即可看到两种方式的结果和耗时。

---

## 三、A2A 全流程演示

展示 A2A 协议核心价值：Agent Card 发现 + 统一协议调用 + 跨 Agent 管道。

**前提**：问答 Agent（9999）和翻译 Agent（9998）都必须运行。

```bash
cd ~/Desktop/miaoa/AI/projects/a2a-demo
source .venv/bin/activate
python client.py
```

输出三段：
1. **Phase 1** — Client 发现两个 Agent 的 Agent Card
2. **Phase 2** — 分别调用问答和翻译
3. **Phase 3** — 跨 Agent 管道：问答结果 → 翻译

---

## 注意事项

| 问题 | 解决 |
|------|------|
| 端口被占用 | `lsof -ti:9999 -ti:9998 \| xargs kill -9` |
| 502 Bad Gateway | AgentCard 序列化异常，检查 server.py 中没有 `url` 字段 |
| pip install a2a-sdk 失败 | 需要 Python ≥ 3.10，本项目用 uv 管理 |