环境准备与依赖安装

在构建 Agent-to-Agent (A2A) 交互系统之前，需确保本地开发环境满足以下基础要求：Python 3.13+ 以及 uv 高性能包管理器。以下步骤展示了如何拉取官方 SDK 并配置隔离的运行环境。

# 获取 A2A 协议官方仓库 (使用 HTTPS 方式)
git clone https://github.com/google/A2A.git
cd A2A/a2a-python-sdk

# 使用 uv 初始化并激活虚拟环境
uv venv .venv
source .venv/bin/activate

# 以可编辑模式安装 SDK 及其核心依赖
uv pip install -e .

技术提示：A2A 协议目前处于早期快速迭代阶段，底层 API 与数据结构可能会发生破坏性变更。在实际生产环境中使用时，请务必参考官方仓库的最新 Release 说明。

启动 A2A 服务端 (Server)

SDK 提供了一个基础的 helloworld 示例，用于演示如何暴露一个符合 A2A 规范的 Agent 服务端点。

# 切换至示例目录并启动 Uvicorn 服务
cd examples/helloworld
uv run python __main__.py

服务启动后，Uvicorn 将默认监听 0.0.0.0:9999 端口。控制台会输出应用初始化日志，并准备好接收来自客户端的 JSON-RPC 请求（如 /.well-known/agent.json 元数据获取和根路径的消息投递）。

运行 A2A 客户端 (Client)

打开一个新的终端会话，确保已激活相同的虚拟环境并处于 helloworld 目录下，执行客户端测试脚本以发起 RPC 调用。

uv run python test_client.py

客户端将依次发送同步消息请求和流式 (Streaming) 消息请求。您将在终端观察到结构化的 JSON-RPC 响应，其中流式响应会将 "Hello World" 拆分为多个数据块（Chunks）依次返回，并在最后一个数据包中将 final 标志位置为 True。

示例架构与核心组件剖析

该示例通过模块化的设计展示了 A2A 服务的标准构建模式，主要包含以下三个核心文件：

helloworld/
├── __main__.py          # 服务入口：路由注册、AgentCard 声明与服务器启动
├── agent_executor.py    # 业务逻辑：Agent 执行器与消息处理实现
└── test_client.py       # 调用方：封装 HTTP 请求的测试客户端

1. 服务配置与路由 (__main__.py)

• 能力声明：定义 Agent 的技能集（Skills），例如基础的文本处理能力。
• AgentCard 构建：生成包含 Agent 身份、版本、支持协议及技能描述的元数据卡片，供其他 Agent 发现与注册。
• 服务绑定：将执行器挂载到 A2A 路由，并启动异步 Web 服务器。

2. 执行器实现 (agent_executor.py)

• HelloWorldAgent：核心业务类。实现 invoke() 方法以处理阻塞式同步请求，实现 stream() 方法以生成器形式yield分块数据。
• HelloWorldAgentExecutor：协议适配层。负责解析 JSON-RPC 载荷，分发至对应的 Agent 方法，并处理任务取消 (Cancel) 与状态重订阅 (Resubscribe) 等生命周期事件。

3. 客户端调用 (test_client.py)

• 演示了如何通过 HTTP POST 发送标准 A2A 请求。
• 展示了任务状态轮询、上下文管理以及流式数据块的异步消费逻辑。

协议与功能特性

• 标准化消息路由：基于 JSON-RPC 2.0 协议处理文本与多模态数据载荷。
• 流式数据分发：支持分块传输机制，实现低延迟的流式响应与长文本生成。
• 任务生命周期控制：提供任务状态查询、上下文保持及主动取消机制，适用于长时间运行的 Agent 任务。
• 异常状态封装：统一拦截并格式化底层执行错误，向调用方返回标准化的错误码与描述。