1. 从零搭建多 Agent 系统为什么单 Agent 一定会撞墙如果你正在搜索“多 Agent 系统怎么搭建”“A2A 协议和 MCP 协议有什么区别”大概率已经踩过这样一个坑单个 Agent 用起来挺爽一旦任务变复杂就开始胡言乱语、工具调错、上下文爆炸。我试过把一个“帮我做竞品调研并生成周报”的任务塞给一个 Agent结果它在第 7 轮工具调用后彻底忘了最初的目标开始重复查同一个网页。这不是模型不够聪明而是架构问题。单个 Agent 同时承担感知、规划、执行、记忆、反思五个职责就像让一个人既当产品经理又当程序员还当测试短期能扛长期必崩。2026 年工程界的共识是把职责拆开用 A2AAgent-to-Agent协议做协作通信用 MCPModel Context Protocol协议做工具调用标准化再用统一的模型接入通道把底层大模型调用链路收敛掉。本文聚焦的就是这条从零到跑通的工程路径。你会拿到三样能直接复制的东西一份可运行的 Agent 分层配置模板、一段 MCP 服务注册示例、一套 A2A 消息流转的验证步骤。适合谁适合已经会写 Python、调过至少一个大模型 API、但还没把多 Agent 系统真正跑起来的开发者。读完你能在本地拉起一个“主 Agent 拆任务 子 Agent 干活 MCP 工具执行”的最小闭环。先说清楚三个概念的分工很多人在这里混淆Agent 是具备自主决策、规划、执行能力的数字实体它理解意图、拆解目标、调用工具、记忆上下文、自我纠错。A2A 解决的是 Agent 之间怎么互相发任务、怎么发现彼此、怎么流式返回进度。MCP 解决的是 Agent 怎么安全统一地调用外部工具和数据不用为每个模型写一套格式。三者关系是A2A 管横向协作MCP 管纵向工具模型接入通道管底层调用。为什么底层调用要单独收敛因为多 Agent 系统里每个 Agent 都要调模型如果每个 Agent 各自配一套 Key、各自处理不同厂商的鉴权格式你的配置文件会变成灾难。统一 Key 通道的价值就在这里——所有 Agent 走同一个 Base URL、同一个 Key、按需切换 Model ID。2. TaoToken 统一 Key 接入多 Agent 系统的模型调用底座多 Agent 系统最容易被低估的成本不是算力是配置管理。假设你有 4 个 Agent规划 Agent 用推理强的模型执行 Agent 用速度快的模型反思 Agent 用长上下文模型工具路由 Agent 用小模型做分类。如果每个 Agent 单独申请 Key、单独记 Base URL、单独处理鉴权头你会有 4 套凭证、4 个故障点。任何一个 Key 过期整个协作链路断掉。统一 Key 通道要解决的就是这个。TaoToken 提供的是一个兼容主流模型调用格式的 API 入口你只需要维护一份凭证通过切换 Model ID 来让不同 Agent 使用不同模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。这里要强调一个工程原则多 Agent 系统里模型调用层必须和 Agent 逻辑层解耦。具体做法是抽一个model_client模块所有 Agent 通过它发请求而不是各自import openai然后硬编码。这样你换通道、换模型、加限流只改一个文件。先看凭证怎么拿。进入控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建后你会得到一串以sk-开头的 Key。这个 Key 就是所有 Agent 共用的凭证。拿到 Key 后先别急着写 Agent先用最小请求验证通道是通的。这一步能帮你排除 80% 的“Agent 不工作其实是 Key 没配对”的问题。验证用的模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 你可以在网页上直接发一条消息确认账号状态。对于长期跑编码类 Agent 的场景比如让 Agent 自动改代码、跑测试、提 PR建议用 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它的计费方式更适合高频、长会话的 Agent 循环不会因为反思环节反复调用而成本失控。如果你用的是 Claude Code 这类工具做 Agent 开发接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对 Anthropic 格式的配置说明。Claude Code 专用接入页是 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。这里有个关键点多 Agent 系统里不同 Agent 可能用不同厂商的模型格式。规划 Agent 可能用 OpenAI 格式执行 Agent 可能用 Anthropic 格式。统一通道的好处是它同时兼容这两种格式你不需要为每个 Agent 装不同的 SDK。下面这张表是我实测下来最省心的配置对照配置项值说明Base URLhttps://taotoken.net/api所有 Agent 共用API Keysk-你的Key所有 Agent 共用Model ID规划推理型模型 ID按需切换Model ID执行快速型模型 ID按需切换Model ID反思长上下文模型 ID按需切换注意最后三行Model ID 是每个 Agent 唯一需要差异化的地方其余全部共用。这就是统一 Key 通道的核心价值——把 N 个 Agent 的 N 套配置压缩成 1 套凭证 N 个模型名。3. 可复制配置Agent 分层模板 MCP 注册 A2A 消息格式这一节是全文最干的部分直接给可复制的配置。分三块Agent 分层配置、MCP 服务注册、A2A 消息格式。先建目录结构这是多 Agent 项目最容易乱的地方agent-system/ ├── config/ │ ├── agents.yaml │ ├── mcp_servers.json │ └── model_client.py ├── agents/ │ ├── orchestrator.py │ ├── researcher.py │ └── analyzer.py └── a2a/ └── message_schema.json第一块Agent 分层配置config/agents.yaml。这份模板定义了每个 Agent 的角色、模型、可用工具和协作对象model_gateway: base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY} timeout: 60 agents: orchestrator: role: 任务规划与分派 model_id: your-reasoning-model-id skills: - task_decomposition - agent_discovery - result_aggregation can_delegate_to: - researcher - analyzer max_iterations: 10 researcher: role: 信息检索与资料收集 model_id: your-fast-model-id skills: - web_search - document_reader mcp_tools: - search_server - file_server max_iterations: 15 analyzer: role: 数据分析与结论生成 model_id: your-long-context-model-id skills: - data_analysis - report_writing mcp_tools: - db_server max_iterations: 12注意model_gateway段所有 Agent 共用base_url和api_key只有model_id在各自节点里差异化。api_key用环境变量注入不要硬编码进文件这是安全底线。第二块MCP 服务注册config/mcp_servers.json。MCP 的核心是标准化工具调用每个工具服务器注册后Agent 通过统一协议调用{ mcpServers: { search_server: { command: python, args: [-m, mcp_search_server], env: { SEARCH_API_KEY: ${SEARCH_API_KEY} }, tools: [ { name: web_search, description: 搜索互联网获取最新信息, input_schema: { type: object, properties: { query: {type: string}, max_results: {type: integer, default: 5} }, required: [query] } } ] }, file_server: { command: python, args: [-m, mcp_file_server], tools: [ { name: read_document, description: 读取本地文档内容, input_schema: { type: object, properties: { path: {type: string} }, required: [path] } } ] }, db_server: { command: python, args: [-m, mcp_db_server], tools: [ { name: query_data, description: 执行只读数据查询, input_schema: { type: object, properties: { sql: {type: string} }, required: [sql] } } ] } } }这里有个安全要点db_server只暴露只读查询工具不要给 Agent 直连生产库的写权限。MCP 的沙箱机制就是干这个的——工具能做什么由注册时的 schema 决定不由模型自由发挥。第三块A2A 消息格式a2a/message_schema.json。A2A 的核心是 Agent Card 和任务消息。Agent Card 是数字名片任务消息是协作载体{ agent_card: { name: researcher, description: 负责信息检索与资料收集, endpoint: http://localhost:8001/a2a, skills: [ { name: web_search, description: 搜索互联网获取最新信息, input_schema: {query: string, max_results: integer} } ], capabilities: { streaming: true, async: true } }, task_message: { task_id: task-20260101-001, from_agent: orchestrator, to_agent: researcher, intent: search_and_collect, payload: { query: 2026年多Agent系统主流框架对比, max_results: 10 }, stream: true, timeout_seconds: 120 } }capabilities.streaming设为 true 后被委托的 Agent 可以像聊天一样实时返回进度而不是等全部干完才回。这对长任务很关键——主 Agent 能知道子 Agent 卡在哪一步。把这三块配置放好后写config/model_client.py做统一调用封装import os import yaml from openai import OpenAI class ModelClient: def __init__(self, config_pathconfig/agents.yaml): with open(config_path, r, encodingutf-8) as f: cfg yaml.safe_load(f) gw cfg[model_gateway] self.client OpenAI( base_urlgw[base_url], api_keyos.environ.get(TAOTOKEN_API_KEY, gw[api_key]), timeoutgw[timeout], ) self.agents cfg[agents] def chat(self, agent_name, messages, toolsNone): agent self.agents[agent_name] kwargs { model: agent[model_id], messages: messages, } if tools: kwargs[tools] tools resp self.client.chat.completions.create(**kwargs) return resp.choices[0].message这段代码的关键是所有 Agent 走同一个self.client只有model参数按 Agent 名切换。你换通道、加限流、开重试只改这一个类。4. 验证请求跑通 A2A 消息流转与 MCP 工具调用配置写完了现在验证。验证分三步先验证模型通道通再验证 MCP 工具能调最后验证 A2A 消息能流转。每一步都有明确的成功标志不要跳步。第一步验证模型通道。写一个最小脚本from config.model_client import ModelClient mc ModelClient() msg mc.chat(orchestrator, [ {role: user, content: 用一句话说明你的职责} ]) print(msg.content)跑通的话你会看到模型返回类似“我负责任务规划与分派”的内容。如果这里报 401说明 Key 没配对先解决这个再往下走。如果报连接超时检查base_url是否写成了https://taotoken.net/api注意结尾不要多加斜杠。第二步验证 MCP 工具调用。MCP 的验证要点是模型能正确生成符合 schema 的工具调用参数。写一个测试tools [{ type: function, function: { name: web_search, description: 搜索互联网获取最新信息, parameters: { type: object, properties: { query: {type: string}, max_results: {type: integer} }, required: [query] } } }] msg mc.chat(researcher, [ {role: user, content: 帮我搜一下2026年A2A协议的最新进展} ], toolstools) if msg.tool_calls: call msg.tool_calls[0] print(工具名:, call.function.name) print(参数:, call.function.arguments) else: print(模型没有触发工具调用检查 description 是否清晰)成功标志是打印出工具名: web_search和一段 JSON 参数。如果模型没触发工具调用八成是description写得太模糊——MCP 工具描述要写清楚“什么时候用”不是“这是什么”。第三步验证 A2A 消息流转。这一步模拟主 Agent 把任务委托给子 Agent子 Agent 流式返回进度。先起一个最小的 A2A 服务端from fastapi import FastAPI from fastapi.responses import StreamingResponse import json, asyncio app FastAPI() app.post(/a2a) async def handle_task(task: dict): async def stream(): steps [接收任务, 解析意图, 调用工具, 生成结果] for i, step in enumerate(steps): yield json.dumps({ task_id: task[task_id], step: i 1, status: step, progress: (i 1) / len(steps) }, ensure_asciiFalse) \n await asyncio.sleep(0.5) return StreamingResponse(stream(), media_typeapplication/x-ndjson)启动后用客户端发一条 A2A 任务消息import requests, json task { task_id: task-20260101-001, from_agent: orchestrator, to_agent: researcher, intent: search_and_collect, payload: {query: 2026年多Agent系统主流框架对比}, stream: True } resp requests.post( http://localhost:8001/a2a, jsontask, streamTrue ) for line in resp.iter_lines(): if line: print(json.loads(line.decode()))成功标志是逐行打印出进度接收任务 → 解析意图 → 调用工具 → 生成结果progress从 0.25 涨到 1.0。这就是 A2A 流式协作的最小闭环。端到端联调检查清单按顺序过一遍检查项命令/动作通过标志模型通道跑 model_client 测试返回正常文本Key 有效性检查环境变量无 401MCP 工具触发带 tools 发请求返回 tool_callsMCP 参数格式检查 arguments符合 schemaA2A 服务启动访问 /a2a返回流式数据A2A 消息流转发 task_message逐行打印进度多 Agent 协作orchestrator 委托 researcher子任务完成回传5. 本篇常见错排查401、local proxy failed、reading choices、OAuth多 Agent 系统联调时报错往往不在 Agent 逻辑而在接入层。这一节把最高频的四个报错拆开讲每个都给定位方法和修复动作。报错一401 Unauthorized。这是最高频的。现象是模型调用直接返回鉴权失败。定位顺序先确认环境变量TAOTOKEN_API_KEY是否真的注入到进程里很多人写在.env但没export或者用了source但新开终端忘了。再确认 Key 有没有多余空格——从控制台复制时经常带上换行。最后确认base_url和 Key 是否匹配别把 A 通道的 Key 配到 B 通道的地址上。修复动作在model_client.py里加一行启动日志打印base_url和 Key 的前 6 位后 4 位确认无误再跑。报错二local proxy failed。这个报错通常出现在你本地配了某些网络层工具导致请求没走到目标地址。定位方法先用curl直接打https://taotoken.net/api看通不通如果 curl 通但 Python 不通说明是 Python 进程继承了错误的网络配置。修复动作检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY有的话在跑 Agent 前unset掉。注意这里说的是清理本地环境变量不是让你去配任何网络层工具方向反了会更糟。报错三reading choices 相关错误。典型报错是KeyError: choices或AttributeError: NoneType object has no attribute choices。这说明响应体里没有choices字段通常是三种情况请求被限流返回了错误 JSON、模型 ID 写错了返回了错误信息、或者流式响应被当成非流式解析。定位方法在model_client.py里把原始响应打出来resp self.client.chat.completions.create(**kwargs) print(RAW:, resp)如果resp里是错误信息按信息提示改。如果是流式加streamTrue并用for chunk in resp逐块读。修复动作给chat方法加异常捕获把原始响应写进日志别让choices的 KeyError 掩盖真正的错误。报错四OAuth 相关错误。现象是提示 token 过期或授权失败。多 Agent 系统里出现这个通常是因为某个 Agent 用了需要 OAuth 的工具服务器而凭证没刷新。定位方法检查mcp_servers.json里每个 server 的env段看有没有需要 OAuth 的字段。修复动作把 OAuth 凭证的刷新逻辑抽成独立模块在工具调用前检查有效期快过期就刷新。不要在每个 Agent 里各写一套刷新逻辑会重复刷新导致冲突。还有一个高频坑CC Switch、Cline MCP、Codex auth.json 这三类工具配置时必须写全三件套——Base URL、Key、Model ID。少任何一个都会报错而且报错信息往往不直接指向缺失项。Base URL 填https://taotoken.net/apiKey 填你的sk-开头凭证Model ID 填你实际要用的模型名。三个都对齐工具才能正常连上。排查的通用原则先隔离层级。模型通道问题用 curl 验MCP 问题用单独脚本验A2A 问题用最小服务端验。不要在整条链路一起跑的时候排查那样你分不清是哪一层挂了。6. 把最小闭环跑稳之后下一步该做什么到这里你已经有了一个能跑的多 Agent 最小闭环主 Agent 拆任务通过 A2A 委托给子 Agent子 Agent 通过 MCP 调用工具所有模型调用走统一 Key 通道。这个闭环的价值不在于它多智能而在于它每一层都可替换、可观测、可排障。下一步的工程动作我建议按这个顺序推进。先把日志补全每个 Agent 的每次模型调用、每次工具调用、每次 A2A 消息都记一条结构化日志字段包括agent_name、model_id、tool_name、latency_ms、token_used。没有日志的多 Agent 系统出问题就是黑盒。再把重试和降级加上模型调用超时就重试重试两次还失败就降级到备用 Model IDA2A 子 Agent 超时就由主 Agent 接管或换一个子 Agent。最后把 Agent Card 的发现机制从硬编码改成注册中心这样加新 Agent 不用改主 Agent 代码。如果你要长期跑编码类 Agent比如让 Agent 自动改代码、跑测试、提 PR用 Coding Plan 的计费方式更合适地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。高频循环的 Agent 最怕成本失控包月方式能把预算锁死。接入过程中遇到鉴权、格式、工具注册的问题先翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 大部分报错在里面有对照。需要新建或轮换 Key去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。想先验证某个模型在你这套 Agent 里的表现用模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 快速试。最后说一个我踩过的坑多 Agent 系统最容易过度设计的地方是“反思层”。很多人一上来就给每个 Agent 加反思循环结果 token 消耗翻三倍效果提升有限。我的建议是反思只加在主 Agent 的结果聚合环节子 Agent 专注干活别自己反思自己。等主 Agent 发现子 Agent 结果不对再触发重派任务。这样既省成本又让职责清晰。