AstrBot/openspec/a2a.md

A2A (Agent-to-Agent) 协议规范

概述

A2A（Agent-to-Agent）是由 Google Cloud 发起的开放协议，旨在促进不同 AI Agent 之间的互操作性。 A2A 得到了超过 50 家技术合作伙伴（如 Atlassian, Box, Cohere, Langchain, MongoDB, PayPal, Salesforce, SAP, ServiceNow 等）的支持。

核心目标：让不同供应商构建或使用不同技术框架的 Agent 能在动态、多代理生态系统中进行有效通信和协作。

A2A 专注于"互联互通"，与 ACP（Agent Communication Protocol）形成互补关系。

实现状态

组件	状态	说明
A2A Client	❌ 不计划	作为参考协议，不做实现
A2A Server	❌ 不计划	参考文档
AgentCard 发现	❌ 不计划	-

相关协议: ACP（本地 Agent 通信）, agent-message（消息处理框架）

与 ACP 的互补关系

维度	A2A	ACP
定位	跨平台、开放生态	本地优先、受控自治
目标	互联互通	紧密协同
场景	分布式任务调度、跨厂商系统	IDE 编码助手、本地进程
网络	互联网、云端	本地进程、边缘设备
透明度	不透明（Agent 作为黑盒）	透明（每步可见可控）
控制权	Agent 主导	Client 主导

设计原则

• 拥抱代理能力：允许 Agent 在自然的、非结构化模式下协作，无需共享内存、工具或上下文
• 基于现有标准：建立在 HTTP, SSE, JSON-RPC 等广泛接受的标准之上
• 默认安全：支持企业级身份验证和授权
• 支持长时间运行：从快速任务到数小时甚至数天的复杂研究
• 模态无关：支持文本、音频、视频流、表单、iframe 等

三层模型

第一层：数据模型

核心对象：

• AgentCard — 描述 Agent 能力的 JSON 文件
• Task — 有状态的任务实体
• Message — 传递指令、上下文、思考过程
• Artifact — 不可变的输出
• Part — 原子内容单元

第二层：抽象操作

方法	描述
SendMessage	发送消息
SendStreamingMessage	发送流式消息
GetTask	获取任务状态和结果
ListTasks	列出任务
CancelTask	取消任务
SubscribeToTask	订阅任务更新
GetExtendedAgentCard	获取扩展 AgentCard

第三层：协议绑定

• JSON-RPC over HTTP（主要）
• gRPC（原生支持）
• HTTP+JSON/REST

参与者

• User（用户）：使用 Agent 系统完成任务的人类或服务
• Client（客户端）：代表用户向 Agent 请求操作的实体
• Server（服务端）：提供服务的不透明（黑盒）远程 Agent

核心数据模型

AgentCard

托管在 /.well-known/agent-card.json，用于服务发现：

{
  "name": "research-agent",
  "description": "专业的研究分析 Agent",
  "version": "1.0.0",
  "provider": {
    "organization": "Example Corp",
    "url": "https://example.com"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extensions": []
  },
  "skills": [
    {
      "id": "web-search",
      "name": "Web Search",
      "tags": ["search", "research"],
      "examples": [
        {"user": "Search for recent AI news", "agent": "I'll search for recent AI news for you."}
      ]
    }
  ],
  "securitySchemes": {},
  "url": "https://api.example.com/a2a"
}

Task

{
  "id": "task-001",
  "contextId": "session-123",
  "status": {
    "state": "TASK_STATE_WORKING",
    "timestamp": "2024-01-01T00:00:00Z"
  },
  "artifacts": [
    {
      "artifactId": "artifact-001",
      "name": "report",
      "parts": [
        {"type": "text", "text": "分析报告内容..."}
      ]
    }
  ],
  "history": [
    {
      "messageId": "msg-001",
      "role": "ROLE_USER",
      "parts": [{"type": "text", "text": "分析一下最新 AI 趋势"}]
    }
  ],
  "metadata": {}
}

任务状态机（8 个状态）：

SUBMITTED → WORKING → {
  COMPLETED (终态)
  FAILED (终态)
  CANCELED (终态)
  REJECTED (终态)
  INPUT_REQUIRED (中断态)
  AUTH_REQUIRED (中断态)
}

Message + Part

{
  "messageId": "msg-001",
  "role": "ROLE_USER",
  "parts": [
    {"type": "text", "text": "Hello"},
    {"type": "file", "file": {"name": "doc.pdf", "uri": "https://..."}},
    {"type": "data", "data": {"key": "value"}}
  ],
  "referenceTaskIds": []
}

消息格式

SendMessage

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "parts": [{"type": "text", "text": "分析最新 AI 趋势"}]
    },
    "taskId": "optional-existing-task-id",
    "sessionId": "session-123"
  }
}

SendStreamingMessage

{
  "jsonrpc": "2.0",
  "id": "req-002",
  "method": "SendStreamingMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "parts": [{"type": "text", "text": "写一段 Python 代码"}]
    }
  }
}

流式响应

HTTP/1.1 200 OK
Content-Type: text/event-stream

event: message
data: {"task":{"id":"task-1","status":{"state":"TASK_STATE_WORKING"}}}

event: message
data: {"message":{"parts":[{"type":"text","text":"我来帮你"}]}}

event: task
data: {"task":{"id":"task-1","status":{"state":"TASK_STATE_COMPLETED"},"artifacts":[...]}}

v1.0 重要变化：流式结束不再依赖 final 字段，而应依据任务状态和流关闭。

传输层

HTTP(S)/WSS（主要）

POST /a2a HTTP/1.1
Host: api.example.com
Content-Type: application/json
A2A-Version: 1.0.0

{"jsonrpc":"2.0","id":"req-001","method":"SendMessage",...}

gRPC

完整的 gRPC 服务定义，适用于高性能场景。

服务发现

GET /.well-known/agent-card.json HTTP/1.1
Host: api.example.com

{
  "name": "research-agent",
  ...
}

安全认证

支持的认证方式

• OAuth 2.0：authorization_code, client_credentials, device_code
• OpenID Connect：discovery_url
• API Key：query, header, cookie
• HTTP Auth：Bearer, Basic
• Mutual TLS (mTLS)

AgentCard 安全声明

{
  "securitySchemes": {
    "oauth2": {
      "type": "oauth2",
      "flows": ["authorization_code"],
      "authorizationUrl": "https://auth.example.com"
    }
  },
  "securityRequirements": [
    {"oauth2": ["read", "write"]}
  ]
}

错误码

码值	名称	描述
-32700	Parse Error	无效的 JSON
-32600	Invalid Request	格式错误的请求
-32601	Method Not Found	未知方法
-32602	Invalid Params	无效参数
-32603	Internal Error	服务器内部错误
-32100	Agent Not Found	未找到 Agent
-32101	Agent Not Ready	Agent 未就绪
-32102	Task Not Found	任务不存在
-32103	Task Timeout	任务超时
-32104	Task Canceled	任务已取消
-32105	Capability Not Supported	Agent 不支持该能力
-32106	Authentication Failed	认证失败
-32107	Authorization Failed	授权失败

适用场景

1. 智能客服

• 多轮对话管理
• 知识库集成
• 自动化工单处理

2. 开发协作

• 代码审查辅助
• 文档自动化
• 测试用例生成

3. 数据分析

• 数据清洗与转换
• 可视化报表生成
• 异常检测与告警

4. 企业级 Agent 网络

                    认证网关
                       ↓
           ┌──────────┼──────────┐
           ↓          ↓          ↓
       HR Agent   IT Agent   财务 Agent

5. Agent Marketplace

开发者发布 Agent → AgentCard 注册 → 用户发现和调用

v1.0 迁移注意事项

• 流式结束：不再依赖 final 字段，应依据任务状态和流关闭
• 术语统一：使用 canceled（不是 cancelled）
• 服务参数：A2A-Version、A2A-Extensions 等需要显式处理
• taskId 生成：新任务的 taskId 由服务端生成，客户端不应自造

相关资源

• GitHub 仓库
• 技术规范
• API 文档