多Agent-A2A协作入门指南：三大角色+四大对象，全面掌握Agent协作必备知识（建议收藏）

1. 先把 A2A 协作的“人话版”讲清楚A2A 全称 Agent-to-Agent是一套让多个 Agent 互相发现、互相派活、互相回传结果的通信约定。你可以把它理解成公司里的“工单系统”用户提需求前台Client接单并拆解后台的专业同事Remote Agent干活干完把成果Artifact挂回工单上。它适合谁适合已经在写单 Agent、想往多 Agent 编排走的人也适合做智能客服、售后工单、招聘筛选这类“一个入口、多个专业角色”的团队。这一篇我不铺概念直接按“三大角色 四大对象”的线索把 Agent Card、Task、Message 这些核心对象串成一条能跑起来的链路。你会看到可复制的 Agent Card 配置骨架、Task/Message 的字段示例以及本地联调验证的完整步骤。中间涉及模型调用时我会用 TaoToken 的 API 做演示因为它的接口格式和主流 SDK 兼容拿来跑通链路比较省事。先把三个角色钉死后面所有对象都挂在这三个角色上用户User提需求的一方可以是人也可以是上游服务。客户端Client代表用户按 A2A 协议发请求的实体它本身也可以是个 Agent。远程 AgentRemote Agent真正干活的 Agent对 Client 来说是黑盒只通过 Agent Card 暴露能力。四大对象则是它们之间流转的“物料”Agent Card 是名片Task 是工单Message 是对话Artifact 是交付物。下面逐个拆。2. TaoToken 前置把模型调用这层先铺好多 Agent 协作里每个 Remote Agent 背后通常都要调模型。如果每个 Agent 各自去对接不同厂商的 Key联调阶段会非常乱。我的做法是统一走一个兼容 OpenAI 协议的入口TaoToken 就是干这个的官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要先拿到 API Key入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到之后本地先验证一下这层通不通再往上搭 A2A不然出错时你分不清是模型层的问题还是协议层的问题。# 先验证模型调用这层是否可用 curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [ {role: user, content: 用一句话说明什么是A2A协议} ] }返回里能看到choices[0].message.content就说明这层通了。如果你更想先在网页里试模型效果可以直接用模型对话页https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。长期要跑编码类 Agent 或者多轮 Agent 编排的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意联调阶段建议把模型名、base_url、Key 都放进环境变量别硬编码进 Agent Card 或代码里Agent Card 是公开给 Client 发现的写死密钥等于把钥匙挂在门上。3. 可复制配置Agent Card 骨架与 Task/Message 字段3.1 Agent Card 配置骨架Agent Card 是 Remote Agent 的“名片”Client 靠它决定要不要把活派给你。下面这份骨架可以直接改{ name: ResumeFilterAgent, description: 根据岗位需求筛选候选人简历并给出推荐, url: http://localhost:8001/a2a, provider: { organization: MyTeam, url: http://localhost:8001 }, version: 1.0.0, authentication: { schemes: Bearer }, defaultInputModes: [text/plain], defaultOutputModes: [text/plain, application/json], capabilities: { streaming: true, pushNotifications: false }, skills: [ { id: resume-filter, name: 简历筛选, description: 输入岗位JD与候选人列表输出匹配度排序, tags: [recruit, filter, ranking], examples: [ 筛选这5位候选人中谁最适合后端岗位, 按技能匹配度给候选人排序 ], outputModes: [application/json] } ] }几个字段容易踩坑url必须是 Client 能访问到的真实地址本地联调写localhost没问题但换成容器或远程部署时要改成可达地址skills[].id是 Client 路由任务的依据别重复capabilities.streaming如果声明为 true服务端就得真的支持流式返回否则 Client 会等不到分片。3.2 Task 字段示例Task 是工单本体Client 发起的每个任务都有唯一 ID状态在 submitted、working、completed、failed、canceled 之间流转。{ id: task-7f3a9c21, contextId: ctx-recruit-001, status: { state: working }, artifacts: [], history: [], metadata: { priority: high, source: client-agent } }contextId用来把同一轮会话里的多个 Task 串起来比如“筛选”和“安排面试”属于同一个招聘上下文就共用这个 ID。history会累积 Message方便回溯。3.3 Message 字段示例Message 是 Client 和 Remote Agent 之间的对话单元一个 Message 可以带多个 part支持文本、文件、结构化数据。{ role: user, messageId: msg-001, taskId: task-7f3a9c21, contextId: ctx-recruit-001, parts: [ { type: text, text: 请分析以下5位候选人是否符合后端岗位需求并推荐最佳面试人选。 } ], metadata: {} }role只有 user 和 agent 两种Client 发的是 userRemote Agent 回的是 agent。messageId由发送方生成保证唯一即可。3.4 一次完整的请求-响应Client 派活时发的是 JSON-RPC 风格请求{ jsonrpc: 2.0, id: 1, method: tasks/send, params: { id: task-7f3a9c21, message: { role: user, parts: [ {type: text, text: 请分析以下5位候选人是否符合后端岗位需求。} ] }, metadata: {} } }Remote Agent 干完活回的是带 Artifact 的结果{ jsonrpc: 2.0, id: 1, result: { id: task-7f3a9c21, contextId: ctx-recruit-001, status: {state: completed}, artifacts: [ { name: result, parts: [ {type: text, text: 第三位候选人匹配度最高建议优先安排面试。} ] } ] } }看到status.state变成completed且artifacts里有内容这条链路就算跑通了。4. 本地联调验证从发现到回传的完整步骤4.1 起一个最小 Remote Agent用 Python 起一个只做回声的 Agent重点是把 Agent Card 暴露出去、把 Task 接住。# remote_agent.py from fastapi import FastAPI, Request import uuid app FastAPI() AGENT_CARD { name: EchoAgent, description: 回声Agent用于联调验证, url: http://localhost:8001/a2a, version: 1.0.0, defaultInputModes: [text/plain], defaultOutputModes: [text/plain], capabilities: {streaming: False}, skills: [ { id: echo, name: 回声, description: 原样返回输入文本, tags: [debug], examples: [hello] } ] } app.get(/.well-known/agent.json) def agent_card(): return AGENT_CARD app.post(/a2a) async def handle_task(req: Request): body await req.json() params body.get(params, {}) task_id params.get(id, str(uuid.uuid4())) text params[message][parts][0][text] return { jsonrpc: 2.0, id: body.get(id), result: { id: task_id, status: {state: completed}, artifacts: [ {name: result, parts: [{type: text, text: fecho: {text}}]} ] } }启动pip install fastapi uvicorn uvicorn remote_agent:app --port 80014.2 Client 侧做服务发现并发任务# client_agent.py import requests, uuid BASE http://localhost:8001 # 1. 服务发现 card requests.get(f{BASE}/.well-known/agent.json).json() print(发现Agent:, card[name], 技能:, [s[id] for s in card[skills]]) # 2. 发任务 task_id ftask-{uuid.uuid4().hex[:8]} payload { jsonrpc: 2.0, id: 1, method: tasks/send, params: { id: task_id, message: { role: user, parts: [{type: text, text: 你好A2A}] } } } resp requests.post(f{BASE}/a2a, jsonpayload).json() print(任务状态:, resp[result][status][state]) print(交付物:, resp[result][artifacts][0][parts][0][text])跑完你应该看到发现Agent: EchoAgent 技能: [echo] 任务状态: completed 交付物: echo: 你好A2A4.3 把模型接进 Remote Agent把回声逻辑换成真实模型调用Remote Agent 才算有“专业能力”。这里用 TaoToken 的兼容接口import os, requests def call_model(prompt: str) - str: resp requests.post( https://taotoken.net/api/v1/chat/completions, headers{ Authorization: fBearer {os.environ[TAOTOKEN_API_KEY]}, Content-Type: application/json }, json{ model: gpt-4o-mini, messages: [{role: user, content: prompt}] } ) return resp.json()[choices][0][message][content]把handle_task里的fecho: {text}换成call_model(text)再跑一遍 Client就能看到模型生成的真实结果回传到 Artifact 里。这一步跑通说明“Client 发现 → 派 Task → Remote Agent 调模型 → 回 Artifact”整条链路是活的。5. 本篇常见错排查Agent Card 拿不到404。检查路径是不是/.well-known/agent.json很多框架默认路径不同Client 的发现地址要和服务端暴露的一致。Task 一直卡在 working。多半是 Remote Agent 没把状态改成 completed或者异常被吞了。在handle_task里加 try/except把异常也包成failed状态回传别让 Client 干等。Message 的 role 写反。Client 发出去必须是userRemote Agent 回必须是agent写反了有些 Client 会直接丢弃。contextId 每次都不一样。同一轮会话里多个 Task 要共用 contextId否则历史串不起来多轮协作会断。模型调用 401。检查TAOTOKEN_API_KEY是否注入到进程环境以及 base_url 是不是https://taotoken.net/api别多加斜杠或路径。流式声明了但没实现。Agent Card 里streaming: true但服务端返回的是整包Client 会解析失败。联调阶段先设 false跑通再开流式。端口冲突。本地同时起多个 Remote Agent 时8001、8002 分开Agent Card 里的 url 也要对应改。6. 继续往下走链路跑通之后下一步通常是加第二个 Remote Agent让 Client 按 skill 路由简历筛选走一个 Agent面试安排走另一个用 contextId 串成一条招聘流水线。这时候你会发现 Agent Card 的 skills 设计得好不好直接决定 Client 能不能准确派活。需要接着调模型或跑多 Agent 编排的API Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你用的是 Claude Code 这类编码 Agent 做联调Anthropic 兼容入口在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_anthropicutm_campaignrewrite 控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。先把 EchoAgent 跑通再换成真实模型最后加第二个 Agent这条路最稳。