1. 多智能体协作的真实痛点模型调用入口太散A2AAgent2Agent协议、ADKAgent Development Kit和 MCPModel Context Protocol这三个词放在一起解决的是同一件事让多个 Agent 各司其职、互相通信、各自调用工具最后拼成一个完整任务。A2A 负责 Agent 之间的任务分发与状态同步ADK 负责定义每个 Agent 的行为和工具集MCP 负责把外部 API 包装成模型友好的工具接口。适合谁适合已经写过单 Agent Demo、现在想把「航班查询」「酒店查询」「行程编排」拆成独立服务、并且希望每个 Agent 都能稳定调用大模型的开发者。但真正落地时第一个卡住的地方往往不是协议本身而是模型调用入口。三个 Agent 分别部署在不同端口每个 Agent 都要调 LLM如果每个 Agent 各自维护一套 API Key、各自处理限流和重试配置会迅速失控。我试过把 Key 写进每个 Agent 的.env结果改一次 Key 要动三个文件本地调试时还容易漏掉某个 Agent 的环境变量。更麻烦的是A2A 的任务分发要求 Host Agent 能快速拿到子 Agent 的响应如果某个 Agent 的模型通道不稳定整个任务链就会卡住。这篇要做的就是把模型调用入口统一收口到 TaoToken让 Flight Search Agent、Hotel Search Agent、Itinerary Planner 三个角色共用同一个 API 通道同时保留 A2A 协议的任务分发结构。下面给出config.toml与settings.json骨架、多 Agent 注册与路由配置以及一次跨 Agent 任务分发的可复现验证步骤。2. TaoToken 前置统一 Key 与 API 通道TaoToken 在这里的角色是「模型调用的统一入口」。它提供兼容 OpenAI 风格的 API 通道你可以把它理解成一个统一的模型网关三个 Agent 不需要各自配置不同的模型供应商 Key只需要指向同一个 base_url用同一个 Key 发起请求。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。具体操作上你需要先拿到一个 API Key。进入控制台创建 Key 的路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完成后在 API Keys 页面复制 Key页面地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。这个 Key 后面会写进三个 Agent 共用的settings.json而不是分散到各自的.env。注意Key 只放在服务端配置文件里不要写进前端 Streamlit 代码或提交到 Git。建议用环境变量注入配置文件里只保留占位符。如果你还没确认模型通道是否可用可以先用模型对话页面做一次最小验证地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认能正常返回内容后再进入下面的多 Agent 配置。3. 可复制配置config.toml 与 settings.json 骨架先给出项目结构三个 Agent 共用一份模型配置各自保留自己的 Agent Card 和工具配置multi_agent_a2a/ ├── config/ │ ├── config.toml # 全局模型与路由配置 │ └── settings.json # 统一 Key 与 base_url ├── flight_search_app/ │ ├── agent.py │ ├── main.py │ └── static/.well-known/agent.json ├── hotel_search_app/ │ ├── langchain_agent.py │ ├── langchain_server.py │ └── static/.well-known/agent.json └── itinerary_planner/ ├── itinerary_agent.py ├── itinerary_server.py └── static/.well-known/agent.jsonconfig.toml负责声明模型通道和 Agent 路由表[model] provider taotoken base_url https://taotoken.net/api default_model gpt-4o timeout_seconds 60 max_retries 3 [agents.flight_search] name Flight Search Agent host localhost port 8000 card_url http://localhost:8000/.well-known/agent.json skill search_flights [agents.hotel_search] name Hotel Search Agent host localhost port 8003 card_url http://localhost:8003/.well-known/agent.json skill search_hotels [agents.itinerary_planner] name Travel Itinerary Planner host localhost port 8005 card_url http://localhost:8005/.well-known/agent.json skill createItinerarysettings.json只放统一 Key 和模型参数三个 Agent 都读这一份{ api_key: ${TAOTOKEN_API_KEY}, base_url: https://taotoken.net/api, model: gpt-4o, temperature: 0, extra_headers: { X-Client: a2a-multi-agent } }读取配置的公共模块可以这样写放在common/config_loader.pyimport json import os import tomllib from pathlib import Path def load_settings(path: str config/settings.json) - dict: raw Path(path).read_text(encodingutf-8) raw raw.replace(${TAOTOKEN_API_KEY}, os.getenv(TAOTOKEN_API_KEY, )) return json.loads(raw) def load_config(path: str config/config.toml) - dict: with open(path, rb) as f: return tomllib.load(f) def build_model_client(): settings load_settings() from openai import OpenAI return OpenAI( api_keysettings[api_key], base_urlsettings[base_url], timeout60, max_retries3, )这样 Flight Search Agent 用 ADK 调模型时只需要把build_model_client()返回的 client 传进去Hotel Search Agent 用 LangChain 时把base_url和api_key传给ChatOpenAI即可。两个 Agent 不再各自维护 Key。4. 多 Agent 注册与路由配置A2A 的核心是 Agent Card 发现机制。每个 Agent 在/.well-known/agent.json暴露自己的能力描述Host Agent 通过读取这些 Card 来知道「谁能做什么」。下面给出 Flight Search Agent 的 Card 骨架{ name: Flight Search Agent, description: Provides flight information based on user queries., url: http://localhost:8000/, version: 1.0.0, defaultInputModes: [text], defaultOutputModes: [text], capabilities: {streaming: false}, skills: [ { id: search_flights, name: Search Flights, description: Searches for flights based on origin, destination, and date., tags: [flights, travel], examples: [Find flights from JFK to LAX tomorrow] } ] }Hotel Search Agent 的 Card 结构相同只改name、url、skills.id和examples。Host Agent 在启动时读取config.toml里的路由表逐个请求card_url把返回的 Card 缓存到内存import httpx from common.config_loader import load_config class AgentRegistry: def __init__(self): self.config load_config() self.cards {} async def discover(self): async with httpx.AsyncClient(timeout10) as client: for key, meta in self.config[agents].items(): if key itinerary_planner: continue resp await client.get(meta[card_url]) resp.raise_for_status() self.cards[key] resp.json() return self.cards def route(self, skill_id: str) - str: for key, card in self.cards.items(): for skill in card.get(skills, []): if skill[id] skill_id: return self.config[agents][key][host] : str( self.config[agents][key][port] ) raise ValueError(fNo agent registered for skill: {skill_id})Host Agent 拿到用户查询后先用模型解析出需要哪些 skill再通过route()找到对应 Agent 的地址构造 A2A 的tasks/send请求发出去。这样新增一个 Agent 只需要在config.toml加一段路由、在对应目录放一份 Agent CardHost Agent 不需要改代码。5. 验证请求与成功结果启动三个 Agent 和 Host Agentexport TAOTOKEN_API_KEY你的Key python -m flight_search_app.main python -m hotel_search_app.langchain_server python -m itinerary_planner.itinerary_server用 curl 模拟一次跨 Agent 任务分发直接向 Host Agent 发请求curl -X POST http://localhost:8005/v1/tasks/send \ -H Content-Type: application/json \ -d { taskId: task-20250615123456, message: { role: user, parts: [{text: 帮我规划从纽约到迈阿密 6 月 15 日出发、6 月 20 日返回的行程2 人}] } }预期返回结构如下state为completedmessages里包含 agent 角色的整合结果{ task: { taskId: task-20250615123456, state: completed, messages: [ {role: user, parts: [{text: 帮我规划从纽约到迈阿密...}]}, {role: agent, parts: [{text: 已为你整合航班与酒店\n1. 航班 DL1234 ...\n2. 酒店 ...}]} ], artifacts: [] } }验证过程中可以观察 Host Agent 的日志正常会依次出现解析查询 → 路由到search_flights→ 收到 Flight Agent 响应 → 路由到search_hotels→ 收到 Hotel Agent 响应 → 模型整合。如果某个 Agent 的模型调用失败日志里会看到 TaoToken 返回的状态码和重试记录因为三个 Agent 共用同一个 client 配置排查时只需要看一处。6. 本篇常见错排查Agent Card 404检查static/.well-known/agent.json是否真的被服务挂载。ADK 和 FastAPI 默认不会自动暴露静态目录需要在 server 启动时显式 mount。用curl http://localhost:8000/.well-known/agent.json确认能返回 JSON。A2A 请求 method 不匹配A2A 的 JSON-RPC 方法名是tasks/send不是task/send或sendTask。Host Agent 构造 payload 时如果 method 写错子 Agent 会返回Method not found。对照第 3 节的config.toml和 Agent Card 里的skills.id检查拼写。模型调用 401说明settings.json里的 Key 没被正确注入。检查TAOTOKEN_API_KEY环境变量是否 export以及config_loader.py里的占位符替换是否生效。如果 Key 正确但仍 401确认base_url是https://taotoken.net/api不要多加路径后缀。LangChain Agent 拿不到 MCP 工具Hotel Search Agent 用MultiServerMCPClient时MCP_CONFIG里的command必须是已安装的可执行命令。先在终端单独跑mcp-hotel-search --connection_type stdio确认能启动再放进 Agent 配置。任务超时A2A 任务链涉及多次模型调用默认 60 秒可能不够。在settings.json里把timeout_seconds调到 120同时确认max_retries不要设太大否则失败时会累积等待时间。7. 接入文档与后续分流如果你在配置过程中遇到 Key 注入或 base_url 的问题可以直接看接入文档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 结构长期跑在本地做编码或 Agent 调试可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合需要持续调用模型通道的开发场景。Claude Code 相关的接入说明在 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite Anthropic 通道说明在 https://taotoken.net/anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentanthropicutm_campaignrewrite 。最后给一个实用技巧三个 Agent 共用settings.json后本地调试时可以在config_loader.py里加一行日志打印当前使用的base_url和模型名这样每次启动都能确认没有读到旧的.env残留。A2A 的任务分发本身不复杂复杂的是让每个 Agent 的模型入口保持一致收口到一处之后排障范围会小很多。