浅谈 A2A SDK 核心组件

A2A（Agent-to-Agent）协议的 SDK 为开发智能体服务端提供了一套稳定、可扩展的基础框架。其中，AgentExecutor、EventQueue、DefaultRequestHandler、A2AStarletteApplication、AgentCard & AgentSkill 是构成整个运行时的关键骨架。本文将逐一介绍这五个组件。

一、AgentExecutor ------ 智能体业务执行引擎

AgentExecutor 是一个 抽象基类（ABC），它定义了所有智能体执行逻辑的标准接口。

class AgentExecutor(ABC):
    @abstractmethod
    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None: ...
    @abstractmethod
    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None: ...

1、核心功能

（1） 执行任务 (execute)

• 从 RequestContext 中读取任务输入（如消息、任务 ID、上下文等）。

• 调用业务逻辑（可同步/异步）。

• 通过 EventQueue 推送任务事件：

  • 状态变化（TaskStatusUpdateEvent）
  • Artifact更新（TaskArtifactUpdateEvent）
  • 新消息（Message）

（2） 取消任务 (cancel)

• 根据任务 ID 停止当前执行。
• 推送取消状态事件。

2、生命周期

1. 被 RequestHandler 调用
2. 初始化上下文（context）
3. 执行业务逻辑
4. 持续向 EventQueue 推送事件
5. 任务结束后更新状态（completed/failed/canceled）

3、设计亮点

• 与传输层解耦 ：AgentExecutor 不关心 HTTP/SSE/WebSocket 的具体实现。
• 可替换性强：任何 Agent 都能用不同的执行逻辑，只要遵守接口。
• 事件驱动 ：不直接返回结果，而是向 EventQueue 写入事件，实现流式响应。

4、使用建议

• 在 execute 中使用 异步 I/O，避免阻塞事件循环。
• 将复杂任务拆分为多个状态事件，而不是一次性推送最终结果。
• 在 cancel 中确保资源释放（文件句柄、异步任务等）。

二、EventQueue ------ 事件流缓冲与分发中心

EventQueue 是 SDK 的 异步事件中转站 ，核心作用是解耦 Agent 执行与 HTTP 推送。

class EventQueue:
    def __init__(self, max_queue_size=1024): ...
    async def enqueue_event(self, event: Event) -> None: ...
    async def dequeue_event(self, no_wait=False) -> Event: ...
    def tap(self) -> 'EventQueue': ...
    async def close(self) -> None: ...

1、核心功能

1. 事件缓冲：存储 Agent 推送的事件，防止直接阻塞执行逻辑。
2. 事件分发 ：支持 tap() 创建子队列，让多个消费者同时订阅同一事件流。
3. 有界队列 ：默认 max_queue_size=1024，防止内存无限增长。

2、设计细节

• 锁保护（_lock）：保证队列关闭/写入的原子性。
• 递归广播 ：enqueue_event 会递归写入到子队列，确保所有订阅者收到相同事件。
• 优雅关闭 ：支持 Python 3.13 的 queue.shutdown()，低版本则通过 queue.join() 实现。

3、生命周期

1. 创建队列（绑定任务）
2. Agent 执行期间不断写入事件
3. HTTP 层从队列中读取事件并推送
4. 任务结束时关闭队列，通知消费者

4、使用建议

• 流式推送必须用 EventQueue，否则会阻塞 Agent 执行。
• 在多客户端订阅时，使用 tap() 而不是共享一个队列实例。
• 队列过大可能导致内存占用，建议监控队列长度。

三、DefaultRequestHandler ------ 协议到业务的适配器

DefaultRequestHandler 是 协议解析器 + 调度器，它负责：

• 接收 A2A JSON-RPC 请求
• 根据方法名路由到正确的业务方法
• 调用 AgentExecutor
• 管理任务存储（TaskStore）

1、核心功能

1. 请求解析

   • 解析 JSON-RPC 请求，提取任务 ID、方法、参数。

2. 任务调度

   • 创建 RequestContext
   • 创建 EventQueue
   • 调用 AgentExecutor.execute

3. 任务管理

   • 使用 TaskStore 存储任务元数据（内存/数据库）。

2、设计亮点

• 解耦业务逻辑 ：不直接执行任务，而是委托给 AgentExecutor。
• 任务可恢复：配合持久化 TaskStore 可支持从中断处继续执行。
• 统一协议入口：支持扩展为自定义 Handler，添加认证/日志。

3、使用建议

• 对长任务应开启 streaming=True，配合 SSE 流式推送。
• 可以在此层做安全校验（如 API Key、JWT）。
• 适合为每种 Agent 定义一个单独的 Handler，以便独立扩展。

四、A2AStarletteApplication ------ 协议服务端容器

A2AStarletteApplication 基于 Starlette 框架，封装了 A2A 协议的 HTTP 路由与 JSON-RPC 处理。

class A2AStarletteApplication(JSONRPCApplication):
    def routes(self, agent_card_url, rpc_url, extended_agent_card_url) -> list[Route]: ...
    def build(self, agent_card_url, rpc_url, extended_agent_card_url, **kwargs) -> Starlette: ...

1、核心功能

1. 路由注册

   • /rpc：JSON-RPC 方法调用
   • /.well-known/agent-card.json：Agent 元信息
   • /v1/card：扩展版 Agent Card（可选，需认证）

2. 应用构建

   • 将路由绑定到 Starlette 实例
   • 返回可直接运行的 ASGI 应用

2、生命周期

1. 创建 A2AStarletteApplication 实例
2. 注入 AgentCard（Agent 元信息）与 RequestHandler
3. 调用 build() 创建 Starlette 应用
4. 通过 Uvicorn/Gunicorn 启动

3、设计亮点

• 内置 JSON-RPC 协议支持，无需额外编写协议解析。
• 可轻松扩展路由（如增加 /metrics、/healthz）。
• 兼容老版本 Agent Card 路径，保证向后兼容性。

4、使用建议

• 在生产环境建议配合 Uvicorn + Gunicorn 多进程部署。
• 可通过 **kwargs 注入 Starlette 中间件（如 CORS、认证）。
• 扩展路由时避免覆盖协议必须的端点。

五、AgentCard & AgentSkill ------ Agent 的"身份证"

AgentCard 和 AgentSkill 是 A2A 协议的 自描述机制，方便其他 Agent 自动发现并理解你的服务能力。

skill = AgentSkill(id="availability_checker", name="Availability Checker", ...)
agent_card = AgentCard(
    name="Nate Agent",
    description="Schedule pickleball games",
    url="http://localhost:10003/",
    skills=[skill],
)

1、AgentCard 核心字段

• name：Agent 名称
• description：功能描述
• url：服务访问地址
• capabilities：能力声明（流式/非流式、支持的 I/O 模式）
• skills：技能列表
• version：版本号

2、AgentSkill 核心字段

• id：技能唯一标识
• name：技能名称
• description：功能描述
• tags：标签
• examples：示例输入

3、设计意义

• 可发现性：客户端可从 AgentCard 读取技能列表，自动调用。
• 可扩展性：可随版本升级添加新技能而不破坏旧接口。

4、使用建议

• 每个技能的描述和示例要足够清晰，方便自动生成提示词。
• capabilities.streaming=True 时，确保 AgentExecutor 能按需推送事件。
• URL 应指向可直接访问的 /rpc 服务入口。

六、核心组件协作图

JSON-RPC 请求 事件流 SSE/WebSocket Client A2AStarletteApplication DefaultRequestHandler AgentExecutor EventQueue AgentCard

七、总结

组件	角色定位	关键作用
AgentExecutor	业务执行引擎	执行任务 & 推送事件
EventQueue	事件中转站	缓冲 & 广播事件流
DefaultRequestHandler	协议适配器	解析请求 & 调度任务
A2AStarletteApplication	协议容器	提供 HTTP/JSON-RPC 接口
AgentCard & AgentSkill	自我描述	公布能力 & 技能

这些组件一起构成了一个 高内聚、低耦合 的 A2A 服务端架构，让智能体之间能够高效、稳定地协作。