旨在提升可靠性的 A2A 扩展¶

Supported in ADKPython 1.27.0

作为更新后的 A2aAgentExecutor 类的一部分，ADK 提供了对 Agent2Agent (A2A) 支持的扩展，以改进消息和数据处理。更新后的版本包含了对核心智能体执行逻辑的架构变更以及对 A2A 的扩展以改进数据处理，同时还提供了与现有 A2A 智能体的向后兼容性。

激活 A2A 扩展选项将指示服务器使用更新后的智能体执行器实现。虽然这次更新提供了多项通用优势，但它主要解决了当 A2A 和 ADK 都在流式传输模式下运行时，旧版 A2A-ADK 实现中存在的关键局限性。新实现解决了以下问题：

消息重复：防止用户消息在任务历史记录中重复。
输出误分类：阻止远程智能体的 ADK 输出被错误地转换为事件思考 (event thoughts)。
子智能体数据丢失：确保远程智能体的 ADK 输出被可靠地保留，消除了当多个智能体嵌套在远程智能体的子智能体树中时的数据丢失。

客户端扩展激活¶

客户端通过传输定义的 A2A 扩展激活机制来指定其使用此扩展的意愿。对于 JSON-RPC 和 HTTP 传输，这通过 X-A2A-Extensions HTTP 标头表示。对于 gRPC，这通过 X-A2A-Extensions 元数据值表示。

要激活该扩展，客户端可以在实例化 RemoteA2aAgent 时指定 use_legacy=False。这将在发送请求的请求扩展中添加 https://google.github.io/adk-docs/a2a/a2a-extension/。激活此扩展意味着服务器将使用新的智能体执行器实现。

from google.adk.agents import RemoteA2aAgent

# 实例化远程 A2A 智能体
remote_agent = RemoteA2aAgent(
    name="remote_agent",
    url="http://localhost:8000/a2a/remote_agent",
    use_legacy=False,
)

如果在请求中检测到 A2A 扩展，A2aAgentExecutor 默认会使用新实现。要选择退出新的智能体执行器实现，客户端只需不发送此扩展（实例化 RemoteA2aAgent 时设置 use_legacy=True），或者在实例化服务器的 A2aAgentExecutor 时设置 use_legacy=True。

工作原理¶

收到请求后，A2aAgentExecutor 会检测该扩展。它理解客户端正请求使用新的智能体执行器逻辑，并据此将请求路由到新实现。为了确认请求已被接受，该扩展随后会包含在发送回客户端的响应元数据中的“已激活扩展 (activated extensions)”列表以及 A2A 事件的元数据中。

Agent Card 定义¶

智能体在它们的 Agent Card 中的 AgentCapabilities.extensions 列表中声明此扩展能力。

AgentExtension 块示例：

{
  "uri": "https://google.github.io/adk-docs/a2a/a2a-extension/",
  "description": "使用新智能体执行器实现的能力",
  "required": false
}