
项目概述
这是一个基于 Agent2Agent (A2A) 协议的数字猜谜游戏示例,展示了三个轻量级 A2A 代理如何协作完成一个经典的猜数字游戏。该项目作为 A2A 协议和 Python SDK 的实践入门示例,具有以下特点:
- 无 LLM 依赖:不需要 API 密钥或大型语言模型
- 本地运行:所有三个代理都在本地运行,无需远程服务器
- 易于安装:最小化外部依赖
- 核心概念演示:展示 A2A 协议的核心功能
代理角色说明
代理 | 角色 | 功能 |
---|---|---|
AgentAlice | 评估者 | 选择一个 1-100 的秘密数字,评估猜测并给出提示 |
AgentBob | CLI 前端 | 中继玩家猜测,显示 Alice 的提示,与 Carol 协商 |
AgentCarol | 可视化器 | 生成猜测历史的文本可视化,应请求随机打乱历史记录 |
代码文件详细分析
1. 配置文件 (config.py
)
AGENT_ALICE_PORT = 8001
AGENT_BOB_PORT = 8002
AGENT_CAROL_PORT = 8003
功能:集中管理端口配置,避免端口冲突。所有代理都从这个模块导入配置,确保端口分配的一致性。
2. AgentAlice (agent_Alice.py
)
核心功能:
- 在启动时随机选择 1-100 的秘密数字
- 实现
NumberGuessExecutor
类处理猜测评估 - 通过 A2A SDK 的
AgentExecutor
接口处理消息
关键方法:
execute()
: 处理新接收的消息,调用process_guess()
评估猜测cancel()
: 拒绝指定的任务
响应类型:
"Go higher"
- 猜测低于秘密数字"Go lower"
- 猜测高于秘密数字"correct! attempts: <n>"
- 猜测正确,显示尝试次数
3. AgentBob (agent_Bob.py
)
核心功能:
- 作为 CLI 前端,连接玩家与其他代理
- 管理游戏状态和历史记录
- 与 Carol 协商排序历史记录
关键方法:
_handle_guess()
: 将猜测转发给 Alice 并返回反馈_negotiate_sorted_history()
: 与 Carol 协商直到历史记录排序_visualise_history()
: 请求并打印格式化的历史可视化play_game()
: 运行交互式 CLI 循环
协商逻辑:
- 发送初始打乱请求给 Carol
- 检查返回的列表是否已排序
- 如果未排序,发送 "Try again" 继续协商
- 如果已排序,发送 "Well done!" 完成协商
4. AgentCarol (agent_Carol.py
)
核心功能:
- 可视化猜测历史记录
- 随机打乱历史记录列表
- 支持多轮对话和任务引用
关键方法:
_handle_initial()
: 处理新对话的初始消息_handle_followup()
: 处理引用现有任务的后续消息execute()
: 根据消息类型分发到相应处理器
技能定义:
history_visualiser
: 生成格式化的猜测历史摘要history_shuffler
: 随机打乱历史记录条目顺序
5. 工具模块 (utils/
)
game_logic.py
核心功能:
process_guess()
: 评估单个猜测并返回反馈build_visualisation()
: 创建人类可读的历史记录渲染is_sorted_history()
: 检查历史记录是否按猜测值排序process_history_payload()
: 处理历史记录相关的请求
protocol_wrappers.py
核心功能:
send_text()
: 同步发送文本消息到目标代理send_followup()
: 发送后续消息,保持对话上下文cancel_task()
: 取消远程代理的任务extract_text()
: 从 Task 或 Message 中提取纯文本
server.py
核心功能:
run_agent_blocking()
: 启动阻塞式代理服务器- 使用 Starlette + Uvicorn 作为 HTTP 服务器
系统架构流程图
graph TD
A[玩家] --> B[AgentBob CLI]
B --> C[AgentAlice 评估者]
B --> D[AgentCarol 可视化器]
C --> E[秘密数字 1-100]
C --> F[评估猜测]
F --> G{猜测结果}
G -->|太低| H[返回 Go higher]
G -->|太高| I[返回 Go lower]
G -->|正确| J[返回 correct! attempts: N]
B --> K[游戏历史记录]
K --> L[发送给 Carol 可视化]
L --> M[生成格式化表格]
M --> N[显示给玩家]
B --> O[协商排序]
O --> P[发送打乱请求]
P --> Q[Carol 随机打乱]
Q --> R{检查是否排序}
R -->|未排序| S[发送 Try again]
R -->|已排序| T[发送 Well done!]
S --> Q
T --> U[更新历史记录]
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
style E fill:#ffebee
style F fill:#e8f5e8
style K fill:#f3e5f5
style O fill:#f3e5f5
消息流程图
sequenceDiagram
participant Player as 玩家
participant Bob as AgentBob
participant Alice as AgentAlice
participant Carol as AgentCarol
Note over Player,Carol: 游戏开始
Player->>Bob: 输入猜测数字
Bob->>Alice: 发送猜测
Alice->>Bob: 返回评估结果
Bob->>Player: 显示提示
Note over Player,Carol: 记录历史
Bob->>Bob: 添加到游戏历史
Note over Player,Carol: 可视化历史
Bob->>Carol: 发送历史记录
Carol->>Bob: 返回格式化表格
Bob->>Player: 显示历史可视化
Note over Player,Carol: 协商排序
Bob->>Carol: 发送打乱请求
Carol->>Bob: 返回打乱后的列表
Bob->>Bob: 检查是否排序
alt 未排序
Bob->>Carol: 发送 "Try again"
Carol->>Bob: 再次打乱列表
Bob->>Bob: 重新检查排序
else 已排序
Bob->>Carol: 发送 "Well done!"
Carol->>Bob: 完成任务
Bob->>Bob: 更新历史记录
end
Note over Player,Carol: 继续游戏或结束
alt 猜测正确
Bob->>Player: 显示胜利消息
else 猜测错误
Player->>Bob: 继续输入猜测
end
使用 uv 运行项目
1. 环境准备
确保已安装 uv:
# 安装 uv (如果尚未安装)
curl -LsSf https://astral.sh/uv/install.sh | sh
2. 项目设置
# 克隆项目
git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/number_guessing_game
# 使用 uv 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate # Linux/macOS
# 或 .venv\Scripts\activate # Windows
# 安装依赖
uv pip install -r requirements.txt
3. 运行游戏
打开三个终端窗口,在每个窗口中激活虚拟环境:
# 终端 1 - 启动 Alice (评估者)
uv run python agent_Alice.py
# 终端 2 - 启动 Carol (可视化器)
uv run python agent_Carol.py
# 终端 3 - 启动 Bob (CLI 前端)
uv run python agent_Bob.py
4. 游戏玩法
在 Bob 的终端中,游戏会提示你输入 1-100 之间的数字。根据 Alice 的反馈继续猜测,直到猜对为止。
示例游戏流程:
Guess the number AgentAlice chose (1-100)!
Your guess: 50
Alice says: Go higher
=== Carol's visualisation (sorted) ===
Guesses so far:
1. 50 -> Go higher
============================
Your guess: 75
Alice says: Go lower
=== Carol's visualisation (sorted) ===
Guesses so far:
1. 50 -> Go higher
2. 75 -> Go lower
============================
Your guess: 62
Alice says: correct! attempts: 3
You won! Exiting…
项目总结
技术特点
-
A2A 协议实践:
- 展示了代理间通信的核心概念
- 实现了消息发送、任务管理和状态跟踪
- 演示了多轮对话和任务引用机制
-
模块化设计:
- 清晰的职责分离:Alice 负责评估,Bob 负责交互,Carol 负责可视化
- 可重用的工具模块,便于扩展和维护
-
错误处理:
- 输入验证和错误提示
- 网络通信异常处理
- 任务取消和超时机制
学习价值
- A2A 入门:为理解 A2A 协议提供了简单易懂的示例
- 代理协作:展示了多个代理如何协作完成复杂任务
- 异步编程:演示了异步消息处理和状态管理
- 协议设计:展示了如何设计清晰的代理接口和技能定义
扩展可能性
- 添加更多代理:可以引入新的代理角色,如统计分析师、策略顾问等
- 增强游戏逻辑:添加更复杂的游戏规则,如时间限制、分数系统等
- 网络部署:将代理部署到不同机器上,演示分布式代理系统
- 集成 LLM:添加 AI 代理,提供智能提示和策略建议
安全考虑
正如项目文档中提到的,在生产环境中:
- 应将外部代理视为不可信实体
- 需要验证和清理所有接收的数据
- 实现适当的安全措施,如输入验证和凭据保护
这个示例为开发者提供了一个安全、可控的环境来学习和实验 A2A 协议,同时展示了构建分布式代理系统的基本模式。
相关案例文章
🚀 入门示例
-
A2A Samples: Hello World Agent
- 使用 A2A Python SDK 构建 Hello World 代理的完整指南
- 包含详细的环境设置和测试说明
-
- 构建货币转换代理的分步指南
- 集成 OpenRouter AI 服务
🐍 Python 实现案例
-
- 使用 a2a-python 创建和连接 GitHub 代理
- 实现代码仓库信息查询功能
-
- 集成 OpenRouter 的旅行规划代理实现
- 使用 Python a2a-sdk 构建
-
- A2A SDK Python 开发深度教程
- 包含工作流程图和实用代码示例
🟨 JavaScript/TypeScript 案例
-
- 使用 TMDB API 和 OpenRouter AI 集成
- Express.js 服务器实现
-
- TypeScript 类型安全实现
- Express.js 服务器 SDK 和流式处理
☕ Java 实现案例
- A2A Java 示例
- Maven 多模块架构
- Spring Boot 服务器 SDK 实现
- AI 翻译服务示例
🔧 框架集成案例
-
- 使用 Google ADK 框架实现 A2A 智能代理系统
- 涵盖完整开发流程
-
- 基于 Google ADK 和 A2A 协议的智能费用报销代理
- 自动生成表单补充信息
-
- 使用 CrewAI 框架构建数据分析代理
- 集成图表生成和数据可视化功能
🛠️ 开发工具
-
A2A Inspector:Agent2Agent 通信调试详解
- 强大的基于 Web 的调试工具
- 实时检查代理卡片和 JSON-RPC 通信
-
- 实现 Google A2A Protocol v0.2.1 的 .NET 库
- 适用于 ASP.NET Core 应用程序
📚 协议理解和最佳实践
-
- 理解 A2A 协议的综合指南
- 核心概念和 AI 代理互操作性优势
-
- Python 实现规范的综合指南
- 涵盖代理卡片、消息传递、任务管理等核心功能
-
- A2A 协议的全面介绍和实践指南
- 从基础概念到高级应用的完整覆盖
🌟 生态系统资源
-
- 探索 Google A2A 协议的完整生态系统
- 包含官方文档、社区实现、示例项目和集成指南
-
- 探索各种 A2A 协议的开源实现
- 包括 Java、TypeScript、Go、Rust、Python 等
通过这些案例文章,你可以深入了解 A2A 协议在不同场景下的应用,从简单的 Hello World 示例到复杂的多代理系统,为你的 A2A 开发之旅提供丰富的参考资源。