SuperAPI AI 工具集

a2a-protocol

智能体与模型

查看项目

更新于 10-26 16:21

技能介绍

用途

本技能面向需要实现或理解 A2A(Agent-to-Agent)协议的场景,帮助用户完成智能体之间的互操作、通信与发现。A2A 是一个开放协议,最初由 Google 创建,现归属 Linux Foundation,使不同底层框架或厂商的 AI 智能体能够互相通信与协作。A2A 与 MCP 互补:MCP 连接模型与工具/数据,A2A 则让智能体作为自主实体进行协作。

触发条件

当用户想要实现 A2A 服务端或客户端、创建或解析智能体卡片(agent card)、询问多智能体通信或智能体间协议、通过 A2A 在智能体之间发送消息、管理 A2A 任务(创建、获取、列出、取消、订阅)、实现流式(SSE)实时更新、配置推送通知 webhook、或询问 A2A 与 MCP 的对比时,应触发本技能。对于仅涉及 MCP 工具/数据集成而不涉及智能体间通信的场景,以及不涉及智能体间通信的普通 LLM API 调用,不应触发。

主要能力

技能涵盖以下协议要点:

  • 协议绑定:JSON-RPC 2.0(HTTP POST,兼容性最广)、gRPC(HTTP/2,高性能、类型化契约)、HTTP+JSON/REST(标准 HTTP,适合简单集成)。
  • 认证方式:API Key(header、query 或 cookie)、HTTP Basic/Bearer、OAuth 2.0、OpenID Connect、双向 TLS(mTLS)。凭据通过 HTTP header 传递,与协议消息分离。
  • 客户端-服务器模型:A2A Client 代表用户或编排器发送请求;A2A Server 是处理任务并返回结果的远程智能体。通信始终由客户端发起。
  • 智能体卡片:位于 /.well-known/agent-card.json 的 JSON 元数据文档,声明智能体身份、端点 URL、能力(流式、推送通知)、安全方案和技能,是智能体互相发现的方式。
  • 任务生命周期:任务状态包括 submitted、working、completed、failed、canceled、input-required、auth-required、rejected;终态为 completed、failed、canceled、rejected。
  • 消息、部件与产物:Message 表示一次通信回合(角色为 user/agent,包含 parts);Part 是最小内容单元(文本、文件、结构化 JSON);Artifact 是智能体产出的命名输出;contextId 用于跨回合分组相关任务。

使用方式

技能提供具体操作示例,包括:通过 curl https://agent.example.com/.well-known/agent-card.json 发现智能体;使用 a2a.sendMessage 发送消息;使用 a2a.sendStreamingMessage 进行流式传输(需智能体卡片声明 capabilities.streaming: true);使用 a2a.getTask 获取任务状态(history_length 控制历史返回);处理 input-required 多轮交互(需同时传递 task_id 和 context_id);使用 a2a.createTaskPushNotificationConfig 配置 webhook 推送通知(URL 必须为 HTTPS);使用 a2a.cancelTask 取消任务。每个 JSON-RPC 请求的 params 中都必须包含 "a2a-version": "1.0"。

适用场景

适用于构建跨厂商智能体协作系统、实现智能体发现与卡片解析、管理长时间运行任务、实现实时流式更新与异步推送通知等场景。

限制与注意事项

  • 技能首次激活时要求首次回复以 🧢 emoji 开头。
  • 流式调用前必须确认智能体卡片声明 capabilities.streaming: true,否则应回退到 sendMessage。
  • task_id 与 context_id 不同:多轮流程中必须同时传递两者,仅传 task_id 会创建新上下文。
  • 推送通知 webhook 必须使用 HTTPS,本地开发可使用 ngrok、localtunnel 等隧道。
  • 任务进入终态后无法再发送消息,继续发送在某些实现中会静默创建新任务。
  • 缺失 a2a-version 会触发 VersionNotSupportedError。
  • 首次激活时会检查已安装的配套技能(通过 ls 若干目录),并针对缺失项提供安装命令 npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>。
  • 参考文件(agent-card.md、protocol-bindings.md、task-states.md)内容较长,仅在需要时加载以节省上下文。