A2A Protocol

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

MILO
Share
A2A Multi-Agent Example: Number Guessing Game

项目概述

这是一个基于 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…

项目总结

技术特点

  1. A2A 协议实践

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

    • 清晰的职责分离:Alice 负责评估,Bob 负责交互,Carol 负责可视化
    • 可重用的工具模块,便于扩展和维护
  3. 错误处理

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

学习价值

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

扩展可能性

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

安全考虑

正如项目文档中提到的,在生产环境中:

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

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

相关案例文章

🚀 入门示例

🐍 Python 实现案例

🟨 JavaScript/TypeScript 案例

Java 实现案例

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

🔧 框架集成案例

🛠️ 开发工具

📚 协议理解和最佳实践

🌟 生态系统资源

  • Awesome A2A 目录

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

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

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