1. 先搞清楚 A2A 到底在解决什么问题如果你写过 Function Calling或者用 MCP 把数据库、文件系统接进过 Agent那你大概率会有一个直觉工具调用已经够用了为什么还要搞一个 A2A我一开始也这么想直到真的动手做一个多 Agent 协作的小项目才发现单 Agent 加一堆工具的模式在“分工”这件事上会迅速变得难以维护。A2A 的全称是 Agent-to-Agent它关注的不是“一个 Agent 怎么调工具”而是“多个 Agent 之间怎么互相委派任务、跟踪状态、交换结果”。MCP 是纵向的把工具和数据源接到 Agent 身上A2A 是横向的让 Agent 和 Agent 之间能对话。两者不冲突一个项目里经常同时存在。这篇内容面向的是刚接触 A2A、想跑通第一个协作示例的小白程序员。我会用 Agent Card、Message、Task 这三个核心概念做线索配合 TaoToken 的统一 Key 和 API 通道把多个 Agent 的调用入口统一配置好然后完整走一遍“发现能力 → 发送消息 → 创建任务 → 拿到结果”的流程。你跟着做能拿到一份可复制的 settings.json 和 config.toml 骨架以及一次真实的 Agent 间消息与任务流转验证。先说清楚适合谁会一点 Python 或 Node能看懂 JSON 和 TOML本地装过至少一个 Agent 框架比如 Claude Code、Cline、或者自己写的调度脚本但还没真正让两个 Agent 互相说过话。如果你符合这个画像下面的步骤可以直接照搬。2. 用 TaoToken 统一多个 Agent 的调用入口多 Agent 协作第一个让人头疼的地方不是协议本身而是每个 Agent 都要配一套模型访问凭证。市场 Agent 用一个 Key技术 Agent 用另一个 Key写作 Agent 再换一个配置文件散落在不同目录改一次环境就要同步好几处。更麻烦的是有些 Agent 框架读 settings.json有些读 config.toml格式还不一样。TaoToken 在这里的作用是提供一个统一的 API 通道和 Key 管理入口让多个 Agent 共用同一个访问凭证同时保留各自独立的模型选择。你不需要为每个 Agent 单独申请一套凭证也不用担心某个 Agent 的配置格式和另一个不兼容。具体来说TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的接口调用。你可以在控制台里创建 API Key然后把这个 Key 写进不同 Agent 的配置文件。每个 Agent 通过base_url指向同一个通道通过model字段选择自己需要的模型。这样调度 Agent 用强推理模型做任务分解执行 Agent 用快模型做具体操作但底层走的是同一套凭证和通道。如果你还没创建过 Key可以先去控制台的 API Keys 页面生成一个。拿到 Key 之后先别急着写进配置文件用一条 curl 命令验证通道是否通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: ping}], max_tokens: 10 }返回里能看到choices字段就说明通道正常。这一步很重要因为后面 Agent 之间的消息流转如果失败你至少能排除“Key 或通道本身有问题”这个因素。注意不要把 Key 硬编码在会提交到 Git 的文件里。用环境变量或者本地.env文件配置文件里引用变量名。3. 可复制的 settings.json 与 config.toml 配置骨架不同 Agent 框架读的配置文件不一样。下面给两份骨架一份是 JSON 格式常见于 Claude Code、Cline 这类工具一份是 TOML 格式常见于一些 Python Agent 框架和 CLI 工具。你按自己用的框架选对应的那份把base_url和api_key替换成 TaoToken 的地址和你自己的 Key。先看 settings.json{ llm: { provider: openai-compatible, base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model: gpt-4o-mini, timeout: 60, max_retries: 2 }, agent: { name: dispatcher-agent, role: dispatcher, a2a: { enabled: true, agent_card_path: ./agent-card.json, listen_port: 8080, peer_agents: [ { name: market-research-agent, card_url: http://localhost:8081/.well-known/agent-card.json }, { name: tech-review-agent, card_url: http://localhost:8082/.well-known/agent-card.json } ] } } }再看 config.toml[llm] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-4o-mini timeout 60 max_retries 2 [agent] name market-research-agent role worker [agent.a2a] enabled true agent_card_path ./agent-card.json listen_port 8081 [[agent.a2a.skills]] id competitor_research name 竞品分析 description 根据产品名称生成竞品分析摘要 input_modes [text/plain] output_modes [text/markdown, application/json]这两份配置的核心逻辑是一样的LLM 部分统一指向 TaoToken 的base_url用同一个环境变量读取 KeyAgent 部分声明自己的角色和 A2A 监听端口调度 Agent 额外配置peer_agents列表指向其他 Agent 的 Agent Card 地址。这里有个容易踩的坑base_url末尾不要多加/v1。TaoToken 的 API 地址是https://taotoken.net/api具体路径由框架自己拼接。如果你手动写成https://taotoken.net/api/v1有些框架会拼成/api/v1/v1/chat/completions直接 404。另外peer_agents里的card_url指向的是 Agent Card 的发现地址不是消息发送地址。Agent Card 里会包含真正的服务 URL调度 Agent 先读 Card再从 Card 里取url字段发消息。这个顺序不能反。4. 写一份能被发现的 Agent CardAgent Card 是 A2A 协作的起点。没有它调度 Agent 不知道对方能做什么、怎么调用、需要什么认证。你可以把它理解成一张 JSON 格式的“能力名片”放在一个约定好的路径下通常是/.well-known/agent-card.json。下面是一个可以直接用的 Agent Card 示例对应上面 config.toml 里的市场调研 Agent{ name: market-research-agent, description: 负责行业趋势、竞品信息和商业模式分析, url: http://localhost:8081/a2a, version: 1.0.0, capabilities: { streaming: true, pushNotifications: false }, security: [ { BearerAuth: [] } ], skills: [ { id: competitor_research, name: 竞品分析, description: 根据产品名称生成竞品分析摘要输入为产品名输出为 Markdown 格式的分析报告, inputModes: [text/plain], outputModes: [text/markdown, application/json] } ] }几个字段值得单独说。url是消息实际发送的地址调度 Agent 读完 Card 后会往这里 POST。capabilities.streaming表示这个 Agent 支持流式返回如果你的调度逻辑要处理中间片段这个字段要设为 true。skills数组是路由的核心依据调度 Agent 会拿任务描述去匹配 skill 的id或description。写 Agent Card 时最容易犯的错是把description写成广告文案比如“业界领先的智能分析能力”。这种描述对调度 Agent 来说毫无信息量它没法判断这个 skill 到底能不能处理“帮我分析 Cursor 和 Claude Code 的差异”。正确的做法是写清楚输入范围、输出格式和限制条件像上面那样把“输入为产品名输出为 Markdown”写明白。5. 跑通一次完整的 Message 与 Task 流转配置和 Card 都准备好之后就可以验证 Agent 之间的消息流转了。整个过程分三步调度 Agent 读取远程 Agent Card匹配 skill发送 Message远程 Agent 接收后判断任务复杂度简单任务直接返回 Message复杂任务创建 Task调度 Agent 根据返回类型决定是直接读结果还是拿 Task ID 继续跟踪。先启动两个 Agent 进程。假设你已经把上面的配置写进了各自的项目目录市场调研 Agent 监听 8081调度 Agent 监听 8080。启动后用 curl 手动模拟一次调度 Agent 的发现动作curl http://localhost:8081/.well-known/agent-card.json返回的 JSON 里应该能看到skills数组和url字段。确认无误后发送一条 A2A 消息curl -X POST http://localhost:8081/a2a/message:send \ -H Content-Type: application/a2ajson \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { message: { messageId: msg-001, role: ROLE_USER, parts: [ { text: 请分析 Cursor、Claude Code、CodeBuddy 的产品差异 } ] }, configuration: { acceptedOutputModes: [text/markdown, application/json] } }如果任务比较简单远程 Agent 会直接返回一个包含parts的 Message你在返回体里就能读到分析结果。如果任务被判定为复杂任务返回体里会出现task对象包含id、status等字段。这时候你需要拿task.id去查询状态curl http://localhost:8081/a2a/tasks/task-001 \ -H Authorization: Bearer $TAOTOKEN_API_KEY状态会经历submitted、working、completed这几个阶段。当status.state变成completed时artifacts字段里就是最终产出。整个过程中两个 Agent 用的是同一个 TaoToken Key但各自可以选择不同的模型——调度 Agent 用推理强的模型做任务分解市场调研 Agent 用速度快的模型做内容生成。实测下来这套流程在本地跑通大概需要十几分钟主要时间花在配置文件对齐和端口确认上。一旦跑通一次后面加新的 Agent 就是复制 Card 和配置的事。6. 本篇常见错误排查Agent Card 返回 404。检查你的 Agent 框架是否真的把 Card 挂在了/.well-known/agent-card.json路径下。有些框架需要你在配置里显式开启 A2A 服务光写enabled: true不够还要确认监听端口没有被其他进程占用。消息发送返回 401。大概率是Authorization头里的 Key 不对或者环境变量没有正确加载。先用第 2 节的 curl 命令单独验证 TaoToken 通道确认 Key 本身可用再检查 Agent 配置文件里的变量引用写法。Task 一直停在 submitted 状态。这通常说明远程 Agent 收到了消息但没有真正开始执行。检查远程 Agent 的 LLM 配置是否指向了正确的base_url以及模型名是否在 TaoToken 支持的列表里。如果模型名写错Agent 会在调用模型时静默失败Task 状态就不会推进。调度 Agent 找不到匹配的 skill。回到 Agent Card 的skills字段确认id和description是否足够具体。调度逻辑通常会用任务文本去匹配 skill 描述如果描述太泛匹配就会失败。把“分析能力”改成“根据产品名称生成竞品分析摘要”匹配成功率会明显提升。两个 Agent 用了不同的 Key 导致计费混乱。这正是 TaoToken 统一 Key 要解决的问题。把所有 Agent 的api_key都指向同一个环境变量在控制台里就能看到统一的调用记录和用量。如果你发现某个 Agent 的调用没有出现在控制台检查它的配置文件是不是还在用旧的直连地址。跑通第一个 A2A 示例之后下一步可以尝试把 Task 的轮询改成 SSE 流式接收或者给 Agent Card 加上更细粒度的 skill 权限控制。这些进阶操作都建立在同一个基础上统一的调用入口和清晰的 Agent Card。把这两件事做扎实后面的协作链路会顺很多。