A2A协议深度理解与实践
本文档通过实际构建A2A协议的客户端和智能体，深入理解A2A (Agent-to-Agent) 协议的工作原理。我们将按照真实的使用流程，从智能体注册到用户请求处理，完整展示A2A协议的实际应用。// 任务主体id: string;// 任务的唯一标识符// 客户端生成的会话 ID// 任务当前状态history?// 消息历史记录artifacts?// 代理创建的工件集合metadata?//
·
概述
本文档通过实际构建A2A协议的客户端和智能体，深入理解A2A (Agent-to-Agent) 协议的工作原理。我们将按照真实的使用流程，从智能体注册到用户请求处理，完整展示A2A协议的实际应用。
实践流程概览
graph TD
A[构建A2A Client] --> B[构建A2A Agent]
B --> C[第一步：智能体注册]
C --> D[注册逻辑介绍]
D --> E[注册抓包分析]
E --> F[注册相关字段详解]
F --> G[第二步：用户请求处理]
G --> H[请求流程介绍]
H --> I[请求抓包分析]
I --> J[响应抓包分析]
J --> K[相关字段详解]
K --> L[核心概念总结]
A2A Protocol - Agent智能体通信开放标准
A2A Protocol 是一个专门为智能体间通信设计的开放标准协议，旨在实现不同智能体系统之间的无缝协作和信息交换。
核心概念详解
1. AgentCard (智能体卡片) - 智能体的数字身份证
📖 概念定义：
AgentCard (智能体卡片) 是A2A协议中智能体的身份证明和能力说明书，包含智能体的基本信息、支持的功能和连接方式。
🔍 通俗理解：
想象你在招聘网站上看简历：
- 个人信息：姓名、联系方式 = AgentCard的基本信息
- 技能清单：会Python、懂设计 = AgentCard的能力描述
- 工作经验：做过什么项目 = AgentCard的功能说明
- 联系方式：如何联系到这个人 = AgentCard的连接信息
AgentCard就是智能体的数字简历！
🏗️ 核心特征：
- 身份标识：唯一标识一个智能体
- 能力描述：详细说明智能体的功能
- 连接信息：提供如何与智能体通信的方式
- 标准格式：统一的结构便于发现和集成
- 可发现性：支持智能体的自动发现机制
📋 基本结构：
interface AgentCard {
// 基本信息
id: string; // 智能体唯一标识
name: string; // 智能体名称
description: string; // 智能体描述
version: string; // 版本信息
// 能力信息
capabilities: Capability[]; // 能力列表
supportedProtocols: string[]; // 支持的协议
// 连接信息
endpoints: Endpoint[]; // 连接端点
authentication?: AuthInfo; // 认证信息
// 元数据
metadata?: Record<string, any>; // 扩展元数据
tags?: string[]; // 标签
category?: string; // 分类
}
🌟 实际应用示例：
{
"id": "weather-agent-001",
"name": "天气助手",
"description": "提供全球天气查询和预报服务的智能体",
"version": "1.2.0",
"capabilities": [
{
"name": "weather-query",
"description": "查询指定城市的当前天气",
"inputTypes": ["text"],
"outputTypes": ["text", "json"]
}
],
"supportedProtocols": ["A2A-1.0", "JSON-RPC-2.0"],
"endpoints": [
{
"type": "http",
"url": "https://weather-agent.example.com/api",
"methods": ["POST"]
}
],
"tags": ["weather", "forecast", "climate"],
"category": "information-service"
}
2. Task (任务) - 协作的工作单元
📖 概念定义：
Task (任务) 是A2A协议的核心概念，代表一个有状态的工作单元，管理客户端与智能体之间的完整交互过程。
🔍 通俗理解：
想象你在餐厅点餐：
- 创建任务：你告诉服务员"我要一份意大利面"
- 任务处理：厨师开始制作（working状态）
- 需要确认：服务员问"要加芝士吗？"（input-required状态）
- 任务完成：意大利面端上桌（completed状态）
整个从点餐到上菜的完整流程就是一个Task！
🏗️ 核心特征：
- 有状态管理：清晰的生命周期状态
- 会话关联：支持多轮对话和上下文保持
- 结果承载：包含生成的工件(Artifacts)
- 历史记录：保存完整的交互历史
- 可追踪：每个任务都有唯一标识
任务的生命周期与交互：
- 创建: 任务总是由客户端创建
- 状态管理: 任务的状态由远程代理（Server）决定和维护
- 会话关联: 多个任务可以通过可选的 sessionId 归属于同一个会话，方便管理相关的交互
- 代理行为: 收到任务请求后，代理可以采取多种行动：
- 立即满足请求
- 安排稍后执行的工作
- 拒绝请求
- 协商不同的执行方式
- 向客户端索要更多信息
- 委派给其他代理或系统
- 持续交互: 即使任务目标初步达成，客户端仍可在同一任务上下文中请求更多信息或进行修改（例如：“画一只兔子”，然后"把它画成红色"）
- 信息传递: 任务不仅用于传递最终结果（工件）和交互消息（思考、指令等），还维护着任务的状态及其可选的历史记录（状态变化和消息记录）。这对于支持多轮对话式的 AI 交互至关重要
🔄 任务生命周期详解：
1. 📝 submitted (已提交)
- 含义：任务刚被创建，等待处理
- 场景：用户刚发送请求
- 示例：用户问"今天天气怎么样？"
2. ⚙️ working (处理中)
- 含义：智能体正在处理任务
- 场景：智能体正在思考或执行
- 示例：天气智能体正在查询天气数据
3. ❓ input-required (需要输入)
- 含义：需要用户提供更多信息
- 场景：智能体需要澄清或补充信息
- 示例：智能体问"您想查询哪个城市的天气？"
4. ✅ completed (已完成)
- 含义：任务成功完成
- 场景：智能体已生成最终结果
- 示例：返回了完整的天气预报
5. ❌ canceled (已取消)
- 含义：任务被主动取消
- 场景：用户或系统取消了任务
- 示例：用户说"算了，不用查天气了"
6. 💥 failed (执行失败)
- 含义：任务执行过程中出错
- 场景：系统错误或无法完成
- 示例：天气API服务不可用
7. ❔ unknown (状态未知)
- 含义：无法确定任务状态
- 场景：系统异常或通信中断
- 示例：网络连接中断
🌟 完整任务示例：
{
"id": "c9246687-e81d-49a6-8927-ce57e713b7dd",
"sessionId": "dffdcc4b-936f-4be4-bcb0-e4345b001620",
"status": {
"state": "completed",
"timestamp": "2025-05-31T10:28:00Z"
},
"history": [
{
"role": "user",
"parts": [
{
"kind": "text",
"text": "西雅图明天的天气怎么样？"
}
]
}
],
"artifacts": [
{
"artifactId": "c7dbcd81-c04e-47aa-947d-391350a901d9",
"name": "天气查询结果",
"parts": [
{
"kind": "text",
"text": "未来 3 天的天气如下: 1. 明天 (2025年6月1日): 晴天..."
}
]
}
]
}
3. Artifact (工件) - 智能体的最终成果
📖 概念定义：
Artifact (工件) 是A2A协议中智能体生成的最终产出物，代表智能体完成任务后交付给用户的具体成果。
🔍 通俗理解：
想象你请一个设计师朋友帮你设计一个Logo：
- 你的请求是Message（“帮我设计个Logo”）
- 设计师的思考过程也是Message（“我觉得用蓝色比较好”）
- 最终交付的Logo文件就是Artifact（实际的设计成果）
🏗️ 核心特征：
- 结果导向：代表任务的最终输出
- 可持久化：可以保存、传输、重用
- 结构化：有明确的格式和元数据
- 独立性：可以脱离对话上下文独立存在
📋 基本结构：
interface Artifact {
artifactId: string; // 工件唯一标识符
name: string; // 工件名称
description?: string; // 工件描述
parts: Part[]; // 工件内容部分
metadata?: Record<string, any>; // 扩展元数据
}
🌟 实际应用示例：
示例1：天气查询工件
{
"artifactId": "c7dbcd81-c04e-47aa-947d-391350a901d9",
"name": "天气查询结果",
"description": "西雅图未来3天天气预报",
"parts": [
{
"kind": "text",
"text": "未来 3 天的天气如下: 1. 明天 (2025年6月1日): 晴天; 2. 后天 (2025年6月2日): 小雨; 3. 大后天 (2025年6月3日): 大雨。"
}
]
}
示例2：图片生成工件
{
"artifactId": "img-12345-abcde",
"name": "可爱小猫插画",
"description": "根据用户描述生成的卡通风格小猫图片",
"parts": [
{
"kind": "image",
"url": "https://example.com/cat-image.png",
"mimeType": "image/png"
}
]
}
示例3：代码生成工件
{
"artifactId": "code-67890-fghij",
"name": "Python计算器函数",
"description": "实现基本四则运算的Python函数",
"parts": [
{
"kind": "text",
"text": "def calculator(a, b, operation):\n if operation == '+':\n return a + b\n elif operation == '-':\n return a - b\n # ... 更多代码",
"mimeType": "text/x-python"
}
]
}
💡 设计理念：
- 清晰分离：区分过程信息和结果信息
- 结果管理：便于保存和重用生成的内容
- 标准化：统一的工件格式便于不同系统集成
- 可追溯：每个工件都有唯一标识，便于追踪
4. Message (消息) - 智能体间的对话载体
📖 概念定义：
Message (消息) 是A2A协议中的基本通信单元，用于在客户端和智能体之间传递过程信息和交互内容。
🔍 通俗理解：
想象你和朋友微信聊天：
- 你发的每条文字、图片、语音都是Message
- 朋友的回复、表情、状态也都是Message
- 这些Message记录了你们的完整对话过程
在A2A协议中，Message就是智能体间的"聊天记录"！
🏗️ 核心特征：
- 过程导向：记录交互过程，不是最终结果
- 角色明确：区分用户(user)和智能体(agent)
- 内容丰富：支持文本、图片等多种类型
- 结构化：标准的格式便于处理
🎭 消息用途分类：
1. 👤 用户输入 (User Input)
{
"role": "user",
"parts": [
{
"kind": "text",
"text": "帮我写一首关于春天的诗"
}
]
}
2. 🤖 智能体思考 (Agent Thinking)
{
"role": "agent",
"parts": [
{
"kind": "text",
"text": "我需要考虑春天的特征：花开、鸟鸣、温暖..."
}
]
}
3. 📊 状态更新 (Status Update)
{
"role": "agent",
"parts": [
{
"kind": "text",
"text": "正在生成诗歌，请稍等..."
}
]
}
4. ❓ 请求指令 (Request Instruction)
{
"role": "agent",
"parts": [
{
"kind": "text",
"text": "您希望这首诗是什么风格的？古典还是现代？"
}
]
}
5. ❌ 错误信息 (Error Information)
{
"role": "agent",
"parts": [
{
"kind": "text",
"text": "抱歉，我暂时无法访问诗歌数据库"
}
]
}
🌟 多媒体消息示例：
{
"role": "user",
"parts": [
{
"kind": "text",
"text": "请分析这张图片中的内容"
},
{
"kind": "image",
"url": "https://example.com/image.jpg",
"mimeType": "image/jpeg"
}
]
}
💡 设计理念：
- 过程记录：完整记录交互过程
- 角色区分：明确区分用户和智能体
- 内容承载：支持多种类型的内容
- 上下文保持：维护对话的连续性
🔍 与Artifact的区别：
- Message：记录过程交流，如对话、思考、状态
- Artifact：交付最终结果，如文件、图片、代码
5. Part (片段) - 内容的基本载体
📖 概念定义：
Part (片段) 是A2A协议中的内容载体，是Message和Artifact的基本组成单元，用于承载不同类型的具体内容。
🔍 通俗理解：
想象你发朋友圈：
- 文字描述 = 一个text类型的Part
- 配图 = 一个image类型的Part
- 位置信息 = 一个location类型的Part
- 整个朋友圈 = 包含多个Part的Message
Part就像是内容的积木块，可以组合成丰富多样的消息！
🏗️ 核心特征：
- 类型多样：支持文本、图片、文件等多种内容
- 组合灵活：一个Message/Artifact可包含多个Part
- 结构统一：所有类型的Part都有统一的基础结构
- 扩展性强：可以定义新的Part类型
📋 基础结构：
interface Part {
kind: string; // Part类型标识
[key: string]: any; // 类型特定的属性
}
🎨 常见Part类型详解：
1. 📝 文本Part (Text Part)
interface TextPart extends Part {
kind: "text";
text: string; // 文本内容
mimeType?: string; // MIME类型（可选）
}
基础文本示例：
{
"kind": "text",
"text": "今天天气真不错！"
}
带格式的代码示例：
{
"kind": "text",
"text": "def hello():\n print('Hello, World!')",
"mimeType": "text/x-python"
}
2. 🖼️ 图片Part (Image Part)
interface ImagePart extends Part {
kind: "image";
url?: string; // 图片URL
data?: string; // Base64编码的图片数据
mimeType: string; // 图片MIME类型
width?: number; // 图片宽度
height?: number; // 图片高度
}
URL方式示例：
{
"kind": "image",
"url": "https://example.com/cat.jpg",
"mimeType": "image/jpeg",
"width": 800,
"height": 600
}
3. 📁 文件Part (File Part)
interface FilePart extends Part {
kind: "file";
name: string; // 文件名
url?: string; // 文件URL
data?: string; // Base64编码的文件数据
mimeType: string; // 文件MIME类型
size?: number; // 文件大小（字节）
}
文件示例：
{
"kind": "file",
"name": "report.pdf",
"url": "https://example.com/files/report.pdf",
"mimeType": "application/pdf",
"size": 1024000
}
4. 🔗 引用Part (Reference Part)
interface ReferencePart extends Part {
kind: "reference";
uri: string; // 引用的URI
title?: string; // 引用标题
description?: string; // 引用描述
}
引用示例：
{
"kind": "reference",
"uri": "https://example.com/article/123",
"title": "A2A协议详解",
"description": "深入了解A2A协议的技术细节"
}
🌟 Part组合应用示例：
示例1：图文混合消息
{
"role": "user",
"parts": [
{
"kind": "text",
"text": "请分析这张图片中的内容："
},
{
"kind": "image",
"url": "https://example.com/screenshot.png",
"mimeType": "image/png"
}
]
}
示例2：多文件工件
{
"artifactId": "project-files-123",
"name": "网站项目文件",
"parts": [
{
"kind": "file",
"name": "index.html",
"data": "PCFET0NUWVBFIGh0bWw+...",
"mimeType": "text/html"
},
{
"kind": "file",
"name": "style.css",
"data": "Ym9keSB7IGZvbnQtZmFtaWx5...",
"mimeType": "text/css"
}
]
}
🔄 Part的处理流程：
确定内容类型 → 选择Part类型 → 填充具体数据 → 设置元数据
💡 设计理念：
- 内容分离：将不同类型的内容分别处理
- 类型安全：明确的类型标识避免处理错误
- 组合灵活：支持富媒体内容的组合
- 扩展性：可以轻松添加新的内容类型
- 标准化：统一的Part结构便于系统集成
🔍 Part类型选择指南：
| 内容类型 | 推荐Part类型 | 关键属性 |
|---|---|---|
| 纯文本 | text | text |
| 代码 | text | text + mimeType |
| 图片 | image | url/data + mimeType |
| 文档 | file | name + url/data |
| 链接 | reference | uri + title |
🔗 五大核心概念关系图
层次关系
AgentCard (智能体身份)
↓
Task (工作单元)
├── Message[] (对话记录)
│ └── Part[] (内容载体)
└── Artifact[] (最终成果)
└── Part[] (内容载体)
协作流程
1. AgentCard发现 → 找到合适的智能体
2. Task创建 → 开始协作任务
3. Message交换 → 进行对话交流
4. Artifact生成 → 产出最终结果
5. Part承载 → 传递具体内容
实际应用场景
场景1：天气查询
用户 → 天气智能体 (通过AgentCard发现)
创建Task → 发送Message("今天天气怎么样？")
智能体处理 → 生成Artifact(天气预报结果)
结果包含Part(文本天气信息)
场景2：图片生成
用户 → AI画师 (通过AgentCard发现)
创建Task → 发送Message("画一只猫")
智能体询问 → Message("什么风格？")
用户回答 → Message("卡通风格")
智能体生成 → Artifact(包含image类型的Part)
任务相关接口定义
以下是与任务相关的关键接口定义：
// 任务主体
interface Task {
id: string; // 任务的唯一标识符
sessionId: string; // 客户端生成的会话 ID
status: TaskStatus; // 任务当前状态
history?: Message[]; // 消息历史记录
artifacts?: Artifact[]; // 代理创建的工件集合
metadata?: Record<string, any>; // 扩展元数据
}
// 任务状态及附带消息
interface TaskStatus {
state: TaskState;
message?: Message; // 向客户端提供的额外状态更新
timestamp?: string; // ISO 日期时间值
}
// 任务状态枚举
type TaskState =
| "submitted"
| "working"
| "input-required"
| "completed"
| "canceled"
| "failed"
| "unknown";
// 用于创建、继续或重启任务的客户端参数
interface TaskSendParams {
id: string; // 任务 ID
sessionId?: string; // 会话 ID (如果未设置，服务器会为新任务创建)
message: Message; // 发送的消息
historyLength?: number; // 要检索的最近消息数量
pushNotification?: PushNotificationConfig; // 断开连接时服务器发送通知的配置
metadata?: Record<string, any>; // 扩展元数据
}
// 服务器在 sendSubscribe 或 subscribe 请求期间发送的状态更新事件
interface TaskStatusUpdateEvent {
id: string;
status: TaskStatus;
final: boolean; // 指示事件流是否结束
metadata?: Record<string, any>;
}
// 服务器在 sendSubscribe 或 subscribe 请求期间发送的工件更新事件
interface TaskArtifactUpdateEvent {
id: string;
artifact: Artifact;
metadata?: Record<string, any>;
}
// 推送通知配置
interface PushNotificationConfig {
// 配置细节（具体结构未在源文档中详细说明）
}
第一部分：智能体注册流程
1.1 注册逻辑介绍
在A2A协议中，智能体必须先进行注册才能被其他智能体发现和使用。注册过程包括：
- 智能体启动：智能体服务启动并准备接受连接
- 生成AgentCard：创建包含身份信息和能力描述的智能体卡片
- 注册到发现服务：将AgentCard提交到注册中心或广播给其他智能体
- 维持注册状态：定期更新注册信息，保持在线状态
1.2 注册流程图
1.3 注册抓包分析
以下是天气智能体注册时的实际网络抓包数据：
注册请求抓包
POST /registry/agents HTTP/1.1
Host: registry.a2a.example.com
Content-Type: application/json
Authorization: Bearer agent-token-12345
Content-Length: 1024
{
"id": "weather-agent-001",
"name": "天气助手",
"description": "提供全球天气查询和预报服务的智能体",
"version": "1.2.0",
"capabilities": [
{
"name": "weather-query",
"description": "查询指定城市的当前天气",
"inputTypes": ["text"],
"outputTypes": ["text", "json"]
}
],
"endpoints": [
{
"type": "http",
"url": "https://weather-agent.example.com/api",
"methods": ["POST"]
}
],
"supportedProtocols": ["A2A-1.0"],
"tags": ["weather", "forecast"],
"category": "information-service"
}
注册响应抓包
HTTP/1.1 201 Created
Date: Sat, 31 May 2025 10:25:00 GMT
Server: A2A-Registry/1.0
Content-Type: application/json
Content-Length: 156
{
"status": "registered",
"agentId": "weather-agent-001",
"registrationId": "reg-12345-abcde",
"expiresAt": "2025-06-01T10:25:00Z",
"discoveryUrl": "https://registry.a2a.example.com/agents/weather-agent-001"
}
1.4 注册相关字段详解
🎫 AgentCard核心字段
基本信息字段：
id: “weather-agent-001” - 智能体的全局唯一标识符name: “天气助手” - 智能体的可读名称description: 智能体功能的详细描述version: “1.2.0” - 智能体的版本号
能力描述字段：
capabilities: 智能体支持的功能列表name: 功能名称description: 功能描述inputTypes: 支持的输入类型outputTypes: 支持的输出类型
连接信息字段：
endpoints: 连接端点列表type: 连接类型（http、websocket等）url: 连接地址methods: 支持的HTTP方法
元数据字段：
supportedProtocols: 支持的协议版本tags: 标签，便于分类和搜索category: 智能体分类
📋 注册响应字段
状态信息：
status: “registered” - 注册状态agentId: 确认注册的智能体IDregistrationId: 注册记录的唯一标识
生命周期管理：
expiresAt: 注册过期时间discoveryUrl: 智能体发现地址
1.5 官网AgentCard示例
根据A2A协议官方文档，以下是标准的AgentCard结构：
interface AgentCard {
// 基本信息
id: string; // 智能体唯一标识
name: string; // 智能体名称
description: string; // 智能体描述
version: string; // 版本信息
// 能力信息
capabilities: Capability[]; // 能力列表
supportedProtocols: string[]; // 支持的协议
// 连接信息
endpoints: Endpoint[]; // 连接端点
authentication?: AuthInfo; // 认证信息
// 元数据
metadata?: Record<string, any>; // 扩展元数据
tags?: string[]; // 标签
category?: string; // 分类
}
完整的图像生成智能体示例：
{
"id": "image-gen-ai-v2",
"name": "AI画师",
"description": "基于文本描述生成高质量图像的AI智能体",
"version": "2.1.0",
"capabilities": [
{
"name": "text-to-image",
"description": "根据文本描述生成图像",
"inputTypes": ["text"],
"outputTypes": ["image/png", "image/jpeg"],
"parameters": [
{
"name": "prompt",
"type": "string",
"required": true,
"description": "图像描述文本"
},
{
"name": "style",
"type": "string",
"required": false,
"options": ["realistic", "cartoon", "abstract"],
"default": "realistic"
}
]
}
],
"supportedProtocols": ["A2A-1.0"],
"endpoints": [
{
"type": "http",
"url": "https://ai-artist.example.com/generate",
"methods": ["POST"]
}
],
"authentication": {
"type": "api-key",
"required": true
},
"tags": ["image", "generation", "ai", "art"],
"category": "creative-service"
}
第二部分：用户请求处理流程
2.1 请求流程介绍
当智能体注册完成后，用户就可以通过客户端向智能体发送请求。完整的请求处理流程包括：
- 用户发起查询：用户在客户端输入"西雅图明天的天气怎么样？"
- 客户端发现智能体：通过注册中心找到合适的天气智能体
- 建立连接：客户端与天气智能体建立通信连接
- 发送请求：客户端向智能体发送包含用户查询的Task
- 智能体处理：天气智能体处理请求并查询天气数据
- 返回响应：智能体返回包含天气信息的Artifact
2.2 请求处理流程图
2.3 用户请求抓包分析
以下是用户查询天气时的实际网络抓包数据（这就是我们之前分析的抓包）：
请求抓包详解
POST / HTTP/1.1
Host: 127.0.0.1:10000
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
User-Agent: python-httpx/0.28.1
Content-Length: 387
Content-Type: application/json
请求体（JSON-RPC 2.0格式）：
{
"id": "f62e1773-eaa2-4eae-89da-b878942ad255",
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"configuration": {
"acceptedOutputModes": ["text", "text/plain", "image/png"]
},
"message": {
"contextId": "dffdcc4b-936f-4be4-bcb0-e4345b001620",
"kind": "message",
"messageId": "baf94796-ef89-46c6-b2e2-1c73072a41c6",
"parts": [
{
"kind": "text",
"text": "西雅图明天的天气怎么样？"
}
],
"role": "user"
}
}
}
2.4 智能体响应抓包分析
响应抓包详解
HTTP/1.1 200 OK
date: Sat, 31 May 2025 10:28:00 GMT
server: uvicorn
content-length: 787
content-type: application/json
响应体（JSON-RPC 2.0格式）：
{
"id": "f62e1773-eaa2-4eae-89da-b878942ad255",
"jsonrpc": "2.0",
"result": {
"artifacts": [
{
"artifactId": "c7dbcd81-c04e-47aa-947d-391350a901d9",
"description": "",
"name": "天气查询结果",
"parts": [
{
"kind": "text",
"text": "未来 3 天的天气如下: 1. 明天 (2025年6月1日): 晴天; 2. 后天 (2025年6月2日): 小雨; 3. 大后天 (2025年6月3日): 大雨。"
}
]
}
],
"contextId": "dffdcc4b-936f-4be4-bcb0-e4345b001620",
"history": [
{
"contextId": "dffdcc4b-936f-4be4-bcb0-e4345b001620",
"kind": "message",
"messageId": "baf94796-ef89-46c6-b2e2-1c73072a41c6",
"parts": [
{
"kind": "text",
"text": "西雅图明天的天气怎么样？"
}
],
"role": "user",
"taskId": "c9246687-e81d-49a6-8927-ce57e713b7dd"
}
],
"id": "c9246687-e81d-49a6-8927-ce57e713b7dd",
"kind": "task",
"status": {
"state": "completed"
}
}
}
2.5 请求响应字段详解
🔵 JSON-RPC 2.0标准字段
请求字段：
id: “f62e1773-eaa2-4eae-89da-b878942ad255” - 请求唯一标识符jsonrpc: “2.0” - JSON-RPC协议版本method: “message/send” - 调用的方法名
响应字段：
id: 与请求ID匹配，确保请求-响应配对jsonrpc: “2.0” - 协议版本result: 成功响应的结果对象
🟢 A2A协议专有字段
请求中的params字段：
configuration: 配置对象acceptedOutputModes: [“text”, “text/plain”, “image/png”] - 接受的输出格式
message: 消息对象（符合Message接口）contextId: 会话上下文IDkind: “message” - 消息类型messageId: 消息唯一IDparts: 消息内容数组（Part[]类型）role: “user” - 消息角色
响应中的result字段：
artifacts: 智能体生成的工件数组artifactId: 工件唯一IDname: “天气查询结果” - 工件名称parts: 工件内容（Part[]类型）
contextId: 会话上下文ID（与请求匹配）history: 会话历史记录（Message[]类型）id: 任务IDkind: “task” - 对象类型status: 任务状态state: “completed” - 任务已完成
🔗 关键ID关联分析
ID体系的完整性：
- 请求-响应ID:
f62e1773-eaa2-4eae-89da-b878942ad255(确保配对) - 上下文ID:
dffdcc4b-936f-4be4-bcb0-e4345b001620(保持会话连续性) - 消息ID:
baf94796-ef89-46c6-b2e2-1c73072a41c6(唯一标识消息) - 任务ID:
c9246687-e81d-49a6-8927-ce57e713b7dd(标识处理任务) - 工件ID:
c7dbcd81-c04e-47aa-947d-391350a901d9(标识生成结果)
这个完整的ID体系确保了：
- 请求和响应的正确匹配
- 多轮对话的上下文保持
- 消息和任务的可追踪性
- 工件的独立标识和管理
第三部分：A2A协议核心概念总结
通过前面的注册流程和请求处理流程，我们已经看到了A2A协议的实际应用。现在让我们总结一下A2A协议的五大核心概念。
3.1 核心概念速览
A2A协议包含5个核心概念，它们相互配合，构成了完整的智能体间通信体系：
| 概念 | 作用 | 在流程中的体现 |
|---|---|---|
| 🎫 AgentCard | 智能体身份证 | 注册阶段的核心数据结构 |
| 📋 Task | 工作管理器 | 管理整个请求-响应流程 |
| 💬 Message | 对话载体 | 承载用户查询和智能体回复 |
| 🎁 Artifact | 成果容器 | 承载天气预报等最终结果 |
| 🧩 Part | 内容积木 | 承载具体的文本、图片等内容 |
3.2 通俗易懂的概念解释
🎫 AgentCard - 智能体的"身份证"
生活类比：就像你在招聘网站上的简历
- 基本信息：姓名、联系方式 → 智能体的ID、名称、连接地址
- 技能清单：会Python、懂设计 → 智能体的capabilities
- 工作经验：做过什么项目 → 智能体的功能描述
在我们的例子中：天气智能体的AgentCard告诉大家"我叫天气助手，我能查天气，你可以通过HTTP连接我"
📋 Task - 智能体协作的"工单"
生活类比：就像餐厅的订单系统
- 下单：用户说"我要一份意大利面" → 创建Task，状态为submitted
- 制作中：厨师开始做菜 → Task状态变为working
- 需要确认：服务员问"要加芝士吗？" → Task状态变为input-required
- 完成：菜品上桌 → Task状态变为completed
在我们的例子中：用户的天气查询创建了一个Task，管理了从提问到得到答案的整个过程
💬 Message - 智能体间的"聊天记录"
生活类比：就像微信聊天
- 你发的消息：文字、图片、语音 → role为"user"的Message
- 朋友的回复：表情、回复、状态 → role为"agent"的Message
- 聊天记录：完整的对话历史 → Task中的history数组
在我们的例子中：用户的"西雅图明天的天气怎么样？"就是一个Message
🎁 Artifact - 智能体的"作品交付"
生活类比：就像设计师的交付物
- 设计需求：客户说"帮我设计个Logo" → 这是Message（过程沟通）
- 设计师思考：设计师说"我觉得用蓝色好" → 这也是Message（过程沟通）
- 最终Logo文件：实际的设计成果 → 这是Artifact（最终结果）
在我们的例子中：天气预报结果"未来3天的天气如下…"就是一个Artifact
🧩 Part - 内容的"积木块"
生活类比：就像发朋友圈
- 文字描述 → 一个text类型的Part
- 配图 → 一个image类型的Part
- 位置信息 → 一个location类型的Part
- 整个朋友圈 → 包含多个Part的Message
在我们的例子中：用户查询中的"西雅图明天的天气怎么样？"就是一个text类型的Part
3.3 概念间的协作关系
🔗 层次关系（从大到小）
AgentCard (智能体身份)
↓
Task (工作单元)
├── Message[] (对话记录)
│ └── Part[] (内容载体)
└── Artifact[] (最终成果)
└── Part[] (内容载体)
🔄 实际流程中的协作
- 发现阶段：通过AgentCard找到合适的智能体
- 任务创建：创建Task来管理整个协作过程
- 信息交换：通过Message进行对话和状态更新
- 内容承载：所有具体内容都通过Part来承载
- 结果交付：最终成果通过Artifact来交付
🎯 生活化的完整流程
想象你要找人帮忙：
- 看简历（AgentCard）：找到合适的人选
- 下工单（Task）：创建一个工作任务
- 沟通需求（Message + Part）：详细说明你的需求
- 收到作品（Artifact + Part）：获得最终的工作成果
3.4 为什么需要这样设计？
🎯 清晰的职责分工
- AgentCard：负责"找人" - 智能体发现
- Task：负责"管事" - 流程管理
- Message：负责"聊天" - 信息交换
- Artifact：负责"交货" - 结果交付
- Part：负责"装载" - 内容承载
🚀 系统化的优势
- 标准化：所有智能体都遵循相同的规范
- 可追踪：完整的ID体系确保每个环节都可追踪
- 可扩展：支持各种类型的内容和交互模式
- 易理解：清晰的概念边界便于开发和维护
通过这样的设计，A2A协议让复杂的智能体间协作变得简单、标准、可管理！
总结
通过本文档的学习，我们完整地了解了A2A协议的实际应用：
🎯 学习收获
- 实践导向：从实际的注册和请求流程理解协议
- 抓包分析：通过真实的网络数据理解协议细节
- 概念理解：掌握了五大核心概念的作用和关系
- 通俗解释：用生活化的类比理解复杂的技术概念
🚀 应用价值
A2A协议为智能体生态系统提供了统一的通信标准，使得不同厂商、不同技术栈的智能体能够无缝协作，推动了AI智能体网络的发展和普及。
📈 发展前景
随着AI智能体技术的快速发展，A2A协议作为开放标准，将在构建智能体生态系统、促进智能体间协作方面发挥重要作用，为未来的AI应用场景奠定基础。
url: string; // Agent服务URL
version: string; // Agent版本
provider?: { // 提供商信息(可选)
organization: string;
url: string;
};
documentationUrl?: string; // 文档URL(可选)
capabilities: { // 能力配置
streaming?: boolean; // 支持SSE流式传输
pushNotifications?: boolean; // 支持推送通知
stateTransitionHistory?: boolean; // 支持状态转换历史
};
authentication: { // 认证配置
schemes: string[]; // 认证方案
credentials?: string; // 私有Card的凭证
};
defaultInputModes: string[]; // 默认输入MIME类型
defaultOutputModes: string[]; // 默认输出MIME类型
skills: Skill[]; // 技能列表
}
### 官方标准JSON模板
```json
{
"name": "[Agent名称]",
"description": "[Agent功能描述]",
"url": "[Agent服务URL]",
"version": "[版本号]",
"provider": {
"organization": "[组织名称]",
"url": "[组织网站]"
},
"documentationUrl": "[文档URL]",
"capabilities": {
"streaming": false,
"pushNotifications": false,
"stateTransitionHistory": false
},
"authentication": {
"schemes": ["bearer", "basic"],
"credentials": "[凭证信息]"
},
"defaultInputModes": ["text"],
"defaultOutputModes": ["text"],
"skills": [
{
"id": "[技能唯一标识]",
"name": "[技能名称]",
"description": "[技能描述]",
"tags": ["[标签1]", "[标签2]"],
"examples": ["[示例1]", "[示例2]"],
"inputModes": ["text"],
"outputModes": ["text"]
}
]
}
字段说明
| 字段名 | 类型 | 必需 | 说明 |
|---|---|---|---|
name |
String | ✅ | Agent的人类可读名称 |
description |
String | ✅ | Agent功能的人类可读描述 |
url |
String | ✅ | Agent托管的URL地址 |
version |
String | ✅ | Agent版本 |
capabilities |
Object | ✅ | Agent支持的可选能力 |
authentication |
Object | ✅ | Agent的认证要求 |
defaultInputModes |
Array[String] | ✅ | 默认支持的输入MIME类型 |
defaultOutputModes |
Array[String] | ✅ | 默认支持的输出MIME类型 |
skills |
Array[Skill] | ✅ | Agent可执行的能力单元集合 |
第二部分：抓包实例分析
抓包数据结构
根据完整的抓包数据，实际的AgentCard结构是：
{
"capabilities": {
"streaming": false
},
"defaultInputModes": ["text"],
"defaultOutputModes": ["text"],
"description": "提供天气相关的查询功能",
"name": "天气 Agent",
"skills": [
{
"description": "给出某地的天气预告",
"examples": ["给我明天约7天的天气预告"],
"id": "天气预告",
"name": "天气预告",
"tags": ["天气", "预告"]
},
{
"description": "给出某地当前时间的空气质量报告，不做预告",
"examples": ["给我明天当前的空气质量报告"],
"id": "空气质量报告",
"name": "空气质量报告",
"tags": ["空气", "质量"]
}
],
"url": "http://127.0.0.1:10000",
"version": "1.0.0"
}
抓包字段分析
根级字段
| 字段名 | 值 | 类型 | 说明 |
|---|---|---|---|
capabilities |
{"streaming": false} |
Object | 能力配置对象，仅包含streaming字段 |
defaultInputModes |
["text"] |
Array[String] | 默认输入模式，支持文本 |
defaultOutputModes |
["text"] |
Array[String] | 默认输出模式，支持文本 |
description |
"提供天气相关的查询功能" |
String | Agent功能描述 |
name |
"天气 Agent" |
String | Agent显示名称 |
skills |
[...] |
Array[Object] | 技能数组，包含2个技能 |
capabilities对象
| 字段名 | 值 | 类型 | 说明 |
|---|---|---|---|
streaming |
false |
Boolean | 不支持SSE流式响应 |
skills数组中的技能对象
技能1: 天气预告
| 字段名 | 值 | 类型 | 说明 |
|---|---|---|---|
id |
"天气预告" |
String | 技能唯一标识 |
name |
"天气预告" |
String | 技能显示名称 |
description |
"给出某地的天气预告" |
String | 技能功能描述 |
tags |
["天气", "预告"] |
Array[String] | 技能分类标签 |
examples |
["给我明天约7天的天气预告"] |
Array[String] | 使用示例 |
技能2: 空气质量报告
| 字段名 | 值 | 类型 | 说明 |
|---|---|---|---|
id |
"空气质量报告" |
String | 技能唯一标识 |
name |
"空气质量报告" |
String | 技能显示名称 |
description |
"给出某地当前时间的天气质量报告，不做预告" |
String | 技能功能描述 |
tags |
["空气", "质量"] |
Array[String] | 技能分类标签 |
examples |
["给我明天当前的空气质量报告"] |
Array[String] | 使用示例 |
抓包数据特点分析
- 基本字段完整: 包含了核心必需字段(name, description, url, version, skills等)
- capabilities简化: 只包含streaming字段，没有pushNotifications和stateTransitionHistory
- 缺少可选字段:
- 没有authentication字段(可选)
- 没有provider字段(可选)
- 没有documentationUrl字段(可选)
- 实际包含的字段:
- ✅ name: “天气 Agent”
- ✅ description: “提供天气相关的查询功能”
- ✅ url: “http://127.0.0.1:10000”
- ✅ version: “1.0.0”
- ✅ capabilities: {“streaming”: false}
- ✅ defaultInputModes: [“text”]
- ✅ defaultOutputModes: [“text”]
- ✅ skills: [完整的技能数组]
协议要点总结
A2A协议AgentCard核心特性
- 标准化发现机制: 使用
/.well-known/agent.json端点进行智能体发现 - 结构化能力描述: Agent Card提供完整的智能体能力描述
- 技能导向设计: 通过skills数组明确定义智能体的具体能力
- 示例驱动: 每个技能都提供使用示例，便于其他智能体理解如何调用
- 标签系统: 使用tags进行技能分类，便于智能体匹配和发现
- 多模态支持: 通过MIME类型支持文本、文件等多种交互方式
字段分类总结
🟢 A2A协议专有字段: 所有字段都是A2A协议定义的
- 基本信息: name, description, url, version, provider, documentationUrl
- 能力配置: capabilities对象(streaming, pushNotifications, stateTransitionHistory)
- 认证配置: authentication对象(schemes, credentials)
- 交互模式: defaultInputModes, defaultOutputModes
- 技能定义: skills数组(id, name, description, tags, examples, inputModes, outputModes)
🔵 JSON-RPC 2.0 标准字段: 无
Agent Card本身不是JSON-RPC消息，而是HTTP GET请求的响应体
🟡 HTTP标准:
- 传输协议: HTTP/HTTPS
- 内容类型: application/json
- 发现端点: /.well-known/agent.json
这个抓包展示了A2A协议中智能体发现阶段的流程，虽然是简化版本，但包含了核心的智能体能力描述信息。
第三部分：智能体间通信抓包分析
3.1 抓包概览
这是一个完整的A2A协议智能体间通信实例，展示了从请求到响应的完整流程。
3.2 HTTP请求分析
请求头信息
POST / HTTP/1.1
Host: 127.0.0.1:10000
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
User-Agent: python-httpx/0.28.1
Content-Length: 387
Content-Type: application/json
关键信息:
- 方法: POST (智能体间通信使用POST方法)
- 目标: 127.0.0.1:10000 (天气Agent的服务地址)
- 内容类型: application/json (JSON-RPC 2.0格式)
- 用户代理: python-httpx/0.28.1 (Python HTTP客户端)
3.3 JSON-RPC 2.0 请求消息分析
请求消息结构化数据
{
"id": "f62e1773-eaa2-4eae-89da-b878942ad255",
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"configuration": {
"acceptedOutputModes": ["text", "text/plain", "image/png"]
},
"message": {
"contextId": "dffdcc4b-936f-4be4-bcb0-e4345b001620",
"kind": "message",
"messageId": "baf94796-ef89-46c6-b2e2-1c73072a41c6",
"parts": [
{
"kind": "text",
"text": "西雅图明天的天气怎么样？"
}
],
"role": "user"
}
}
}
请求消息字段详解
🔵 JSON-RPC 2.0 标准字段:
id: “f62e1773-eaa2-4eae-89da-b878942ad255” - 请求唯一标识符jsonrpc: “2.0” - JSON-RPC协议版本method: “message/send” - 调用的方法名
🟢 A2A协议专有字段 (在params中):
configuration: 配置对象acceptedOutputModes: [“text”, “text/plain”, “image/png”] - 接受的输出格式
message: 消息对象 (符合Message接口定义)contextId: “dffdcc4b-936f-4be4-bcb0-e4345b001620” - 会话上下文IDkind: “message” - 消息类型messageId: “baf94796-ef89-46c6-b2e2-1c73072a41c6” - 消息唯一IDparts: 消息内容数组 (Part[]类型)kind: “text” - 内容类型text: “西雅图明天的天气怎么样？” - 实际文本内容
role: “user” - 消息角色(用户) - 符合Message接口的role字段
3.4 HTTP响应分析
响应头信息
HTTP/1.1 200 OK
date: Sat, 31 May 2025 10:28:00 GMT
server: uvicorn
content-length: 787
content-type: application/json
关键信息:
- 状态码: 200 OK (请求成功)
- 服务器: uvicorn (Python ASGI服务器)
- 内容长度: 787字节
- 内容类型: application/json
3.5 JSON-RPC 2.0 响应消息分析
响应消息结构化数据
{
"id": "f62e1773-eaa2-4eae-89da-b878942ad255",
"jsonrpc": "2.0",
"result": {
"artifacts": [
{
"artifactId": "c7dbcd81-c04e-47aa-947d-391350a901d9",
"description": "",
"name": "天气查询结果",
"parts": [
{
"kind": "text",
"text": "未来 3 天的天气如下: 1. 明天 (2025年6月1日): 晴天; 2. 后天 (2025年6月2日): 小雨; 3. 大后天 (2025年6月3日): 大雨。"
}
]
}
],
"contextId": "dffdcc4b-936f-4be4-bcb0-e4345b001620",
"history": [
{
"contextId": "dffdcc4b-936f-4be4-bcb0-e4345b001620",
"kind": "message",
"messageId": "baf94796-ef89-46c6-b2e2-1c73072a41c6",
"parts": [
{
"kind": "text",
"text": "西雅图明天的天气怎么样？"
}
],
"role": "user",
"taskId": "c9246687-e81d-49a6-8927-ce57e713b7dd"
}
],
"id": "c9246687-e81d-49a6-8927-ce57e713b7dd",
"kind": "task",
"status": {
"state": "completed"
}
}
}
响应消息字段详解
🔵 JSON-RPC 2.0 标准字段:
id: “f62e1773-eaa2-4eae-89da-b878942ad255” - 与请求ID匹配jsonrpc: “2.0” - JSON-RPC协议版本result: 成功响应的结果对象
🟢 A2A协议专有字段 (在result中):
📦 artifacts数组 - 智能体生成的工件:
artifactId: “c7dbcd81-c04e-47aa-947d-391350a901d9” - 工件唯一IDdescription: “” - 工件描述(此处为空)name: “天气查询结果” - 工件名称parts: 工件内容数组kind: “text” - 内容类型text: “未来 3 天的天气如下…” - 天气预报结果
🔄 contextId: “dffdcc4b-936f-4be4-bcb0-e4345b001620” - 会话上下文ID(与请求匹配)
📚 history数组 - 会话历史记录 (Message[]类型):
contextId: 上下文IDkind: “message” - 历史记录类型messageId: 原始消息IDparts: 原始消息内容 (Part[]类型)role: “user” - 消息角色 (符合Message接口)taskId: “c9246687-e81d-49a6-8927-ce57e713b7dd” - 任务ID
🎯 任务信息:
id: “c9246687-e81d-49a6-8927-ce57e713b7dd” - 任务IDkind: “task” - 对象类型status: 任务状态state: “completed” - 任务已完成
3.6 通信流程分析
完整的请求-响应流程
关键特征分析
🔗 ID关联性:
- 请求ID和响应ID完全匹配:
f62e1773-eaa2-4eae-89da-b878942ad255 - 确保请求-响应的正确配对
🔄 上下文连续性:
- contextId在请求和响应中保持一致:
dffdcc4b-936f-4be4-bcb0-e4345b001620 - 支持多轮对话的上下文管理
📝 消息追踪:
- messageId唯一标识每条消息:
baf94796-ef89-46c6-b2e2-1c73072a41c6 - taskId标识处理任务:
c9246687-e81d-49a6-8927-ce57e713b7dd - 消息结构完全符合Message接口定义，包含role、parts和metadata字段
🎯 任务生命周期:
- 从用户消息到任务完成的完整流程
- 状态从隐含的"processing"到明确的"completed"
3.7 协议特点总结
✅ 优势:
- 标准化: 基于JSON-RPC 2.0，具有良好的互操作性
- 结构化: 清晰的消息结构，便于解析和处理
- 可追踪: 完整的ID体系，支持消息和任务追踪
- 上下文管理: 支持多轮对话的上下文保持
- 工件管理: 支持结构化的输出工件
🔧 技术实现:
- 使用HTTP作为传输协议
- JSON作为数据序列化格式
- UUID作为唯一标识符
- 支持多种输出模式(text, text/plain, image/png)
这个抓包完美展示了A2A协议在实际智能体间通信中的应用，体现了协议的完整性和实用性。
总结
通过对A2A协议官方文档和实际抓包数据的分析，我们可以看到：
🎯 协议设计理念
- 标准化: 基于成熟的JSON-RPC 2.0标准，确保互操作性
- 结构化: 清晰的消息结构和类型定义，便于开发和维护
- 状态管理: 完整的任务生命周期管理，支持复杂的交互场景
- 扩展性: 灵活的元数据和配置机制，支持未来功能扩展
🔧 技术实现特点
- 传输层: HTTP/HTTPS协议，广泛支持
- 应用层: JSON-RPC 2.0，标准化的RPC协议
- 数据格式: JSON，轻量级且易于解析
- 标识符: UUID系统，确保全局唯一性
- 消息系统: 基于Message和Part的结构化通信
- 角色区分: 明确的user/agent角色定义
📈 应用价值
A2A协议为智能体生态系统提供了统一的通信标准，使得不同厂商、不同技术栈的智能体能够无缝协作，推动了AI智能体网络的发展和普及。
🚀 发展前景
随着AI智能体技术的快速发展，A2A协议作为开放标准，将在构建智能体生态系统、促进智能体间协作方面发挥重要作用，为未来的AI应用场景奠定基础。
📚 核心概念学习指南
🎯 学习顺序建议
- Part - 理解内容载体的基础概念
- Message - 掌握通信的基本单元
- Artifact - 了解结果交付机制
- Task - 理解完整的工作流程
- AgentCard - 掌握智能体发现机制
🔍 重点理解要点
🧩 Part是基础
- Part是所有内容的载体，其他概念都依赖它
- 理解不同Part类型的使用场景
- 掌握Part的组合使用方法
💬 Message vs Artifact的区别
- Message：记录过程，如对话、思考、状态更新
- Artifact：交付结果，如文件、图片、代码成果
- 这个区别是理解A2A协议的关键
📋 Task是核心管理者
- Task管理整个协作流程
- 理解7种任务状态的含义和转换
- 掌握任务的生命周期管理
🎫 AgentCard是生态入口
- AgentCard让智能体能够被发现和连接
- 理解能力描述和连接信息的重要性
- 掌握智能体发现机制
💪 实践建议
🚀 从简单开始
- 纯文本交互：先理解基本的Message交换
- 单一工件：理解Artifact的生成和传递
- 多媒体内容：尝试图片、文件等Part类型
- 复杂任务：体验完整的任务生命周期
🔧 动手实践
- 设计AgentCard：为一个虚拟智能体设计完整的卡片
- 模拟对话：设计一个完整的Message交换流程
- 创建工件：设计不同类型的Artifact示例
- 状态管理：理解Task状态的变化过程
🎓 掌握标准
✅ 理解到位的标志
- 能够区分Message和Artifact的用途
- 理解Part的组合使用方式
- 掌握Task的状态管理机制
- 能够设计完整的AgentCard
- 理解五个概念之间的关系
🚀 应用能力
- 能够设计智能体间的协作流程
- 能够处理多媒体内容的传递
- 能够实现复杂的任务管理
- 能够构建智能体发现机制
🎯 核心概念速查表
| 概念 | 作用 | 关键特征 | 主要用途 |
|---|---|---|---|
| AgentCard | 智能体身份证 | 身份标识、能力描述 | 智能体发现、连接建立 |
| Task | 工作管理器 | 状态管理、历史记录 | 流程管理、协作控制 |
| Message | 对话载体 | 角色区分、过程记录 | 信息交换、状态通知 |
| Artifact | 成果容器 | 结果导向、可持久化 | 工作交付、结果保存 |
| Part | 内容积木 | 类型多样、组合灵活 | 内容承载、数据传输 |
火山引擎开发者社区是火山引擎打造的AI技术生态平台，聚焦Agent与大模型开发，提供豆包系列模型（图像/视频/视觉）、智能分析与会话工具，并配套评测集、动手实验室及行业案例库。社区通过技术沙龙、挑战赛等活动促进开发者成长，新用户可领50万Tokens权益，助力构建智能应用。
更多推荐
13
0- 0
已为社区贡献10条内容
所有评论(0)