A2A 多 Agents 示例：数字猜谜游戏

项目概述

这是一个基于 Agent2Agent (A2A) 协议的数字猜谜游戏示例，展示了三个轻量级 A2A 代理如何协作完成一个经典的猜数字游戏。该项目作为 A2A 协议和 Python SDK 的实践入门示例，具有以下特点：

• 无 LLM 依赖：不需要 API 密钥或大型语言模型
• 本地运行：所有三个代理都在本地运行，无需远程服务器
• 易于安装：最小化外部依赖
• 核心概念演示：展示 A2A 协议的核心功能

代理角色说明

代码文件详细分析

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…

项目总结

技术特点

1. A2A 协议实践：

   • 展示了代理间通信的核心概念
   • 实现了消息发送、任务管理和状态跟踪
   • 演示了多轮对话和任务引用机制

2. 模块化设计：

   • 清晰的职责分离：Alice 负责评估，Bob 负责交互，Carol 负责可视化
   • 可重用的工具模块，便于扩展和维护

3. 错误处理：

   • 输入验证和错误提示
   • 网络通信异常处理
   • 任务取消和超时机制

学习价值

1. A2A 入门：为理解 A2A 协议提供了简单易懂的示例
2. 代理协作：展示了多个代理如何协作完成复杂任务
3. 异步编程：演示了异步消息处理和状态管理
4. 协议设计：展示了如何设计清晰的代理接口和技能定义

扩展可能性

1. 添加更多代理：可以引入新的代理角色，如统计分析师、策略顾问等
2. 增强游戏逻辑：添加更复杂的游戏规则，如时间限制、分数系统等
3. 网络部署：将代理部署到不同机器上，演示分布式代理系统
4. 集成 LLM：添加 AI 代理，提供智能提示和策略建议

安全考虑

正如项目文档中提到的，在生产环境中：

• 应将外部代理视为不可信实体
• 需要验证和清理所有接收的数据
• 实现适当的安全措施，如输入验证和凭据保护

这个示例为开发者提供了一个安全、可控的环境来学习和实验 A2A 协议，同时展示了构建分布式代理系统的基本模式。

相关案例文章

🚀 入门示例

• A2A Samples: Hello World Agent

  • 使用 A2A Python SDK 构建 Hello World 代理的完整指南
  • 包含详细的环境设置和测试说明

• A2A SDK 货币代理教程

  • 构建货币转换代理的分步指南
  • 集成 OpenRouter AI 服务

🐍 Python 实现案例

• A2A Python 示例：GitHub 代理

  • 使用 a2a-python 创建和连接 GitHub 代理
  • 实现代码仓库信息查询功能

• A2A 示例：旅行规划助手

  • 集成 OpenRouter 的旅行规划代理实现
  • 使用 Python a2a-sdk 构建

• A2A SDK Python 实践指南

  • A2A SDK Python 开发深度教程
  • 包含工作流程图和实用代码示例

🟨 JavaScript/TypeScript 案例

• A2A JS 示例：电影代理

  • 使用 TMDB API 和 OpenRouter AI 集成
  • Express.js 服务器实现

• A2A JavaScript SDK 完整教程

  • TypeScript 类型安全实现
  • Express.js 服务器 SDK 和流式处理

☕ Java 实现案例

• A2A Java 示例
  • Maven 多模块架构
  • Spring Boot 服务器 SDK 实现
  • AI 翻译服务示例

🔧 框架集成案例

• 使用 ADK 实现 A2A 代理：完整开发指南

  • 使用 Google ADK 框架实现 A2A 智能代理系统
  • 涵盖完整开发流程

• A2A ADK 费用报销代理

  • 基于 Google ADK 和 A2A 协议的智能费用报销代理
  • 自动生成表单补充信息

• A2A CrewAI 分析图表代理

  • 使用 CrewAI 框架构建数据分析代理
  • 集成图表生成和数据可视化功能

🛠️ 开发工具

• A2A Inspector：Agent2Agent 通信调试详解

  • 强大的基于 Web 的调试工具
  • 实时检查代理卡片和 JSON-RPC 通信

• A2A .NET SDK 综合文档

  • 实现 Google A2A Protocol v0.2.1 的 .NET 库
  • 适用于 ASP.NET Core 应用程序

📚 协议理解和最佳实践

• 理解 A2A 协议：综合指南

  • 理解 A2A 协议的综合指南
  • 核心概念和 AI 代理互操作性优势

• A2A 协议规范（Python）

  • Python 实现规范的综合指南
  • 涵盖代理卡片、消息传递、任务管理等核心功能

• 2025 年 A2A 协议完整指南

  • A2A 协议的全面介绍和实践指南
  • 从基础概念到高级应用的完整覆盖

🌟 生态系统资源

• Awesome A2A 目录

  • 探索 Google A2A 协议的完整生态系统
  • 包含官方文档、社区实现、示例项目和集成指南

• A2A 实现集合

  • 探索各种 A2A 协议的开源实现
  • 包括 Java、TypeScript、Go、Rust、Python 等

通过这些案例文章，你可以深入了解 A2A 协议在不同场景下的应用，从简单的 Hello World 示例到复杂的多代理系统，为你的 A2A 开发之旅提供丰富的参考资源。