跳转到内容
CrewAI 中文文档

AMP 上的 A2A

概览

Section titled “概览”

CrewAI AMP 在开源 A2A protocol implementation 的基础上，增加了用于大规模部署分布式 agents 的生产级基础设施。AMP 支持 A2A protocol 0.2 和 0.3 版本。将带有 A2A server 配置的 crew 或 agent 部署到 AMP 后，平台会自动提供分布式状态管理、认证、多传输端点和生命周期管理。

用法

Section titled “用法”

在 crew 中的任意 agent 上添加 A2AServerConfig，然后部署到 AMP。平台会检测带有 server 配置的 agents，并自动注册 A2A 端点、生成 agent cards，以及提供下方所述的基础设施。

from crewai import Agent, Crew, Task
from crewai.a2a import A2AServerConfig
from crewai.a2a.auth import EnterpriseTokenAuth


agent = Agent(
    role="Data Analyst",
    goal="Analyze datasets and provide insights",
    backstory="Expert data scientist with statistical analysis skills",
    llm="gpt-4o",
    a2a=A2AServerConfig(
        auth=EnterpriseTokenAuth()
    )
)


task = Task(
    description="Analyze the provided dataset",
    expected_output="Statistical summary with key insights",
    agent=agent
)


crew = Crew(agents=[agent], tasks=[task])

在 deploying to AMP 之后，平台会注册两层 A2A 端点：

  • Crew 级别：一个汇总的 agent card 位于 /.well-known/agent-card.json，其中每个带有 A2AServerConfig 的 agent 都会作为 skill 列出，并在 /a2a 提供 JSON-RPC 端点
  • 单 agent 级别：隔离的 agent card 和 JSON-RPC 端点挂载在 /a2a/agents/{role}/，每个都有自己的 tenancy

客户端既可以把 crew 当作整体交互，也可以直接针对某个特定 agent。若要通过 crew 级端点把请求路由到某个特定 agent，请在消息 metadata 中加入 "target_agent"，值为该 agent slugify 后的 role 名称（例如 role 为 "Data Analyst" 时使用 "data-analyst"）。如果没有提供 target_agent，请求将由 crew 中的第一个 agent 处理。

A2AServerConfig 的完整选项列表请参见 A2A Agent Delegation。

文件输入与结构化输出

Section titled “文件输入与结构化输出”

AMP 上的 A2A 支持在双向通信中传递文件和请求结构化输出。客户端可以将文件作为 FileParts 发送，并通过在消息中嵌入 JSON schema 来请求结构化响应。server agents 会把文件作为 task 上的 input_files 接收，并在提供 schema 时将结构化数据以 DataParts 返回。详情请参见 File Inputs and Structured Output。

AMP 增加了什么

Section titled “AMP 增加了什么”

分布式状态

持久化的任务、上下文和结果存储

企业级认证

超越简单 bearer token 的 OIDC、OAuth2、mTLS 和 Enterprise token 验证

gRPC 传输

带 TLS 和认证的完整 gRPC server

上下文生命周期

自动检测空闲、过期，并清理长时间运行的对话

签名 Webhook

具备重放保护的 HMAC-SHA256 签名推送通知

多传输

REST、JSON-RPC 和 gRPC 端点可从单次部署中同时提供

分布式状态管理

Section titled “分布式状态管理”

在开源实现中，任务和上下文状态存在于单个进程的内存里。AMP 则将其替换为持久化、分布式存储。

存储层

Section titled “存储层”
存储作用
Task Store持久化 A2A task 状态和元数据
Context Store跟踪对话上下文、创建时间、最近活动时间以及相关任务
Result Store缓存 task 结果以便检索
Push Config Store管理每个 task 的 webhook 订阅

多个 A2A 部署会自动彼此隔离，从而避免在共享基础设施时发生数据冲突。

企业级认证

Section titled “企业级认证”

AMP 为进入的 A2A 请求支持六种认证方案，可按部署单独配置。认证同时适用于 HTTP 和 gRPC 传输。

方案说明用例
SimpleTokenAuth来自 AUTH_TOKEN env var 的静态 bearer token开发、简单部署
EnterpriseTokenAuth通过 CrewAI PlusAPI 进行 token 验证，并带有 integration token claimsAMP 到 AMP 的 agent 通信
OIDCAuth带 JWKS endpoint caching 的 OpenID Connect JWT 验证企业 SSO 集成
OAuth2ServerAuth可配置 scopes 的 OAuth2细粒度访问控制
APIKeyServerAuth通过 header 或 query parameter 验证 API key第三方集成
MTLSServerAuth基于 mutual TLS 证书的认证零信任环境

已配置的认证方案会自动填充 agent card 的 securitySchemes 和 security 字段。客户端会在发起请求前先获取 agent card，从而发现认证要求。

扩展 Agent Cards

Section titled “扩展 Agent Cards”

AMP 通过扩展 agent card 支持基于角色的 skill 可见性。未认证用户看到的是带有公开 skills 的标准 agent card。已认证用户则会收到带有额外能力的扩展 card。

这可以支持如下模式：

  • 面向公众开放基本技能、同时为已认证客户端提供高级技能的公开 agents
  • 根据调用方身份展示不同能力的内部 agents

gRPC 传输

Section titled “gRPC 传输”

如果启用，AMP 会在默认的 JSON-RPC 传输之外提供完整的 gRPC 支持。

  • TLS 终止，并支持可配置的证书和 key 路径
  • gRPC reflection，便于使用 grpcurl 等工具调试
  • 认证，与 HTTP 可用的方案相同
  • 扩展校验，确保客户端支持所需的协议扩展
  • 版本协商，覆盖 A2A protocol 0.2 和 0.3

对于公开多个 agents 的部署，AMP 会自动分配每个 agent 的 gRPC 端口，并协调所有 server 的 TLS、启动和关闭。

上下文生命周期管理

Section titled “上下文生命周期管理”

AMP 会跟踪 A2A 对话上下文的生命周期，并自动处理清理。

生命周期状态

Section titled “生命周期状态”
状态条件动作
Active上下文最近有活动无
Idle在配置的一段时间内没有活动标记为 idle，发出事件
Expired上下文超过最大生命周期标记为 expired，清理相关任务，发出事件

后台清理任务每小时运行一次，扫描空闲和过期上下文。所有状态转换都会发出 CrewAI events，并与平台的可观测性功能集成。

签名推送通知

Section titled “签名推送通知”

当 A2A agent 向客户端 webhook 发送推送通知时，AMP 会使用 HMAC-SHA256 为每个请求签名，以确保完整性并防止篡改。

签名头

Section titled “签名头”
Header作用
X-A2A-Signature采用 sha256={hex_digest} 格式的 HMAC-SHA256 签名
X-A2A-Signature-Timestamp绑定到签名的 Unix timestamp
X-A2A-Notification-Token可选的 notification auth token

安全属性

Section titled “安全属性”
  • 完整性：如果 payload 被修改，签名就会失效
  • 重放保护：签名绑定时间戳，并支持可配置的容差窗口
  • 带退避重试：失败投递会通过指数退避重试

分布式事件流

Section titled “分布式事件流”

在开源实现中，SSE streaming 只能在单个进程内工作。AMP 会在实例之间传播 SSE events，因此即使持有 streaming 连接的实例与执行 task 的实例不同，客户端也能收到更新。

多传输端点

Section titled “多传输端点”

AMP 默认提供 REST 和 JSON-RPC。如果启用，也可以额外提供 gRPC 传输。

传输路径约定说明
REST/v1/message:send, /v1/message:stream, /v1/tasksGoogle API conventions
JSON-RPC标准 A2A JSON-RPC endpoint默认 A2A protocol 传输
gRPC每个 agent 独立分配端口可选的高性能二进制协议

所有激活的传输都会共享相同的认证、版本协商和扩展校验。Agent cards 会根据 agent 和 crew 元数据生成 - roles、goals 和 tools 会变成 skills 和 descriptions - 并自动包含每种已启用传输的接口。它们也可以通过 A2AServerConfig 手动配置。

版本与扩展协商

Section titled “版本与扩展协商”

AMP 会在传输层验证 A2A protocol 版本和扩展。

版本协商

Section titled “版本协商”
  • 客户端通过 A2A-Version header 发送其偏好的版本
  • AMP 会根据支持的版本（0.2、0.3）进行验证，并在未指定时回退到 0.3
  • 协商后的版本会在响应头中返回

扩展验证

Section titled “扩展验证”
  • 客户端通过 X-A2A-Extensions header 声明其支持的扩展
  • AMP 会验证客户端是否支持 agent 需要的所有扩展
  • 缺少必需扩展的客户端请求会收到 UnsupportedExtensionError

下一步

Section titled “下一步”