1. 先聊清楚：multi-agent 智能旅行助手到底在解决什么问题

很多人第一次听到「multi-agent 智能旅行助手」，脑子里浮现的是一个大模型对话框，用户说「帮我规划北京三日游」，模型噼里啪啦吐出一段行程。这种方案能跑通 demo，但一旦要落地就立刻露馅：景点信息是模型编的、天气是过期的、酒店价格根本不存在，用户拿着这份攻略出门，第一天就得在景区门口重新查手机。

真正的工程化做法，是把「规划旅行」这件复杂任务拆成几个职责单一的 Agent，每个 Agent 只干一件事，并且通过 MCP 协议挂载真实的外部工具去拿真实数据。这样做的核心检索词就是multi-agent 智能旅行助手：它不是一个模型在硬扛，而是一组 Agent 分工协作，再配合 MCP 工具链把高德地图、天气、酒店这些真实数据源接进来。

我试过的典型链路是这样的：用户在前端填目的地、日期、偏好、预算，后端 FastAPI 校验数据后调用编排层，编排层依次唤起景点搜索 Agent、天气查询 Agent、酒店推荐 Agent，最后由行程规划 Agent 把三份结果汇总成结构化攻略。每个 Agent 不直接写 HTTP 请求，而是通过 MCP 工具去调用外部 API。这个设计的关键价值在于：Agent 保留了自主决策能力，它自己决定调哪个工具、传什么参数，而不是被写死的函数调用绑住手脚。

为什么不让 Agent 直接调高德 HTTP API？踩过的坑很具体。高德的 POI 搜索有 keywords、city、types、offset、page 十几个参数，你要让模型灵活使用，就得在 prompt 里把每个参数的含义、格式、取值范围全写清楚，prompt 会膨胀到难以维护；返回的 JSON 结构复杂，解析代码高度定制化，接口一改就得跟着改；再加上高德有十几个不同 API，每个都手写函数注册到 Agent 工具列表，代码会变得极其冗长。MCP 把这些脏活封装在 server 进程里，Agent 只需要知道「有个工具叫 amap_maps_text_search，参数是 keywords 和 city」，剩下的交给协议。

这篇文章适合两类人：一是已经会用大模型 API、想往 Agent 工程方向走的开发者；二是手上有个旅行类产品原型、需要把「假数据 demo」升级成「真数据可用系统」的团队。下面我会从统一 Key 接入讲起，一路写到可复制的 Agent 配置、MCP 服务清单和端到端验证，最后把常见报错逐个拆开。所有模型调用统一走 TaoToken 的 API 通道，一个 Key 覆盖多个模型，省得在多家平台之间来回切换。

2. 前置准备：用 TaoToken 统一 Key 打通模型通道

multi-agent 系统最烦的事情之一，是每个 Agent 可能想用不同模型：景点搜索需要便宜快速的模型做意图理解，行程规划需要强推理模型做汇总，酒店比价可能需要长上下文模型读大量文本。如果每个模型都去单独申请 Key、单独配环境变量，项目还没写完，密钥管理先乱成一锅粥。

TaoToken 在这里的角色是统一入口：你注册后拿到一个 API Key，通过同一个 Base URL 就能调用不同模型，Agent 配置里只改 Model ID 就行。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数，配置时别把推广参数拼进去。

第一步，登录后在控制台创建 API Key。地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=console_api_keys ，进去点新建，复制那串以 sk- 开头的密钥。这个 Key 只显示一次，建议立刻存进密码管理器。

第二步，把 Key 写进项目环境变量，不要硬编码进代码。在项目根目录建.env：

# .env TAOTOKEN_API_KEY=sk-你的密钥 TAOTOKEN_BASE_URL=https://taotoken.net/api

Python 侧用 python-dotenv 读取：

import os from dotenv import load_dotenv load_dotenv() API_KEY = os.getenv("TAOTOKEN_API_KEY") BASE_URL = os.getenv("TAOTOKEN_BASE_URL") assert API_KEY, "缺少 TAOTOKEN_API_KEY，请检查 .env"

第三步，确认你要用的模型 ID。不同任务选不同模型是 multi-agent 的常规操作，你可以在模型对话页面先试跑一下，看看哪个模型对工具调用标记的遵循度更好：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models_chat 。我实测下来，工具调用类 Agent 用指令遵循强的模型更稳，规划汇总类用推理能力强的模型输出质量更高。

第四步，如果你打算长期跑编码和 Agent 调试，可以看下 Coding Plan，它更适合高频调用场景：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc ，里面有各语言的调用示例，遇到参数不确定时先翻文档比瞎试快。

这里有个容易被忽略的点：multi-agent 系统里每个 Agent 实例都会发请求，如果你在代码里给每个 Agent 单独 new 一个 client，连接池会浪费。正确做法是全局复用一个 OpenAI 兼容 client，把 base_url 指向 TaoToken，Agent 只传 model 参数区分。这样既省资源，也方便统一加日志和重试。

注意：环境变量文件务必加进.gitignore，Key 泄露是 Agent 项目最常见的安全事故。团队协作时用密钥管理服务分发，不要靠聊天工具传。

3. 可复制配置：HelloAgents 编排 + MCP 工具链落地

这一节是全文的技术核心，我会给出能直接抄的配置片段。整体结构分三层：模型层（TaoToken 统一通道）、编排层（HelloAgents 的 SimpleAgent 组合）、工具层（MCP server 进程）。

先看模型层的统一 client 封装。HelloAgents 的 Agent 内部走 OpenAI 兼容协议，所以我们把 base_url 指到 TaoToken 即可：

# llm_client.py import os from openai import OpenAI _client = None def get_client() -> OpenAI: global _client if _client is None: _client = OpenAI( api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), # https://taotoken.net/api ) return _client def chat(model: str, messages: list, temperature: float = 0.3) -> str: resp = get_client().chat.completions.create( model=model, messages=messages, temperature=temperature, ) return resp.choices[0].message.content

然后是 MCP 服务清单。旅行助手需要挂载的工具按职责分四类，建议每个 MCP server 独立进程，通过 stdio 通信：

MCP 的配置用 JSON 描述，放进项目根目录的mcp_config.json：

{ "mcpServers": { "amap": { "command": "python", "args": ["-m", "mcp_amap_server"], "env": { "AMAP_API_KEY": "${AMAP_API_KEY}" } }, "unsplash": { "command": "python", "args": ["-m", "mcp_unsplash_server"], "env": { "UNSPLASH_ACCESS_KEY": "${UNSPLASH_ACCESS_KEY}" } } } }

注意这里的环境变量是 MCP server 自己的第三方 Key（高德、Unsplash），和 TaoToken 的模型 Key 是两套东西，别混。模型 Key 走.env，工具 Key 走 MCP server 的 env 字段。

接下来是 HelloAgents 的编排配置。四个 Agent 的 prompt 要写得职责单一，工具调用标记格式必须统一。下面是可复制的 Agent 定义：

# agents.py from hello_agents import SimpleAgent, MCPTool ATTRACTION_PROMPT = """你是景点搜索专家。根据用户的城市和偏好，调用 amap_maps_text_search 工具搜索景点。 调用格式：[TOOL_CALL:amap_maps_text_search:keywords=景点,city=城市名] 只返回工具结果，不要编造景点。""" WEATHER_PROMPT = """你是天气查询专家。根据城市名调用 amap_maps_weather 工具。 调用格式：[TOOL_CALL:amap_maps_weather:city=城市名] 返回未来三天天气，不要编造。""" HOTEL_PROMPT = """你是酒店推荐专家。根据城市和住宿档次调用 amap_maps_text_search。 调用格式：[TOOL_CALL:amap_maps_text_search:keywords=酒店,city=城市名] 返回酒店名称、地址、评分。""" PLANNER_PROMPT = """你是行程规划专家。你会收到景点、天气、酒店三份结果和用户原始需求。 请整合成 JSON 格式的行程计划，包含每日景点顺序、餐饮建议、预算明细。 不要调用任何工具，只做信息整合。""" def build_agents(model_fast: str, model_strong: str): amap_tool = MCPTool.from_config("mcp_config.json", "amap") return { "attraction": SimpleAgent(name="景点搜索", prompt=ATTRACTION_PROMPT, model=model_fast, tools=[amap_tool]), "weather": SimpleAgent(name="天气查询", prompt=WEATHER_PROMPT, model=model_fast, tools=[amap_tool]), "hotel": SimpleAgent(name="酒店推荐", prompt=HOTEL_PROMPT, model=model_fast, tools=[amap_tool]), "planner": SimpleAgent(name="行程规划", prompt=PLANNER_PROMPT, model=model_strong, tools=[]), }

编排主流程按顺序调用，注意 planner 的输入要把前三份结果拼进去：

# trip_planner.py from agents import build_agents class TripPlanner: def __init__(self, model_fast="你的快速模型ID", model_strong="你的推理模型ID"): self.agents = build_agents(model_fast, model_strong) def plan(self, city: str, preferences: str, accommodation: str, days: int) -> dict: attraction = self.agents["attraction"].run( f"请搜索{city}的{preferences}景点") weather = self.agents["weather"].run(f"请查询{city}的天气") hotel = self.agents["hotel"].run( f"请搜索{city}的{accommodation}酒店") planner_query = f"""用户需求：{city} {days}天，偏好{preferences}，住宿{accommodation}。 景点结果：{attraction} 天气结果：{weather} 酒店结果：{hotel} 请生成完整行程 JSON。""" return self.agents["planner"].run(planner_query)

如果你用 Claude Code 做本地调试，可以在项目里放一个.claude/settings.json指向统一通道，方便边写边测：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的密钥" } }

这里三件套必须齐全：Base URL 指向 TaoToken 的 API 端点、Key 用控制台创建的那串、Model ID 在 Agent 初始化时显式传入。少任何一个都会在验证阶段报错，下一节会具体讲。

4. 端到端验证：从一次请求看到四个 Agent 依次跑通

配置写完不等于跑通，multi-agent 系统最容易出问题的地方是「中间某个 Agent 静默失败，planner 拿着空结果硬编」。所以验证要分层做，先单 Agent，再全链路。

第一层，验证模型通道。写个最小脚本，确认 TaoToken 的 Key 和 Base URL 能通：

from llm_client import chat print(chat("你的模型ID", [{"role": "user", "content": "回复 OK"}]))

终端输出 OK 就说明模型层没问题。如果这里就报 401，直接跳到第 5 节看排查。

第二层，验证 MCP 工具单独可用。MCPTool 创建时会拉起 server 子进程，先确认进程能起来、工具能列出来：

from hello_agents import MCPTool tool = MCPTool.from_config("mcp_config.json", "amap") print(tool.list_tools()) # 应输出 amap_maps_text_search 等工具名 result = tool.call("amap_maps_text_search", {"keywords": "景点", "city": "北京"}) print(result[:200])

这一步能打印出真实景点数据，说明 MCP 链路通了。如果卡住不动，多半是 server 进程启动失败或 stdio 阻塞，看第 5 节。

第三层，全链路跑一次。启动 FastAPI 后端，用 curl 打规划接口：

uvicorn main:app --reload --port 8000

curl -X POST http://127.0.0.1:8000/api/trip/plan \ -H "Content-Type: application/json" \ -d '{"city":"北京","preferences":"历史文化","accommodation":"经济型","days":3}'

成功时后端日志应该能看到清晰的调用顺序：景点搜索 Agent 先触发amap_maps_text_search，天气 Agent 触发amap_maps_weather，酒店 Agent 再触发一次 POI 搜索，最后 planner 不调工具、直接输出 JSON。返回体大致长这样：

{ "city": "北京", "days": 3, "itinerary": [ {"day": 1, "spots": ["故宫", "景山公园"], "meals": ["午餐：王府井"], "budget": 320} ], "weather": "未来三天晴转多云，18-26℃", "hotels": [{"name": "某连锁酒店", "rating": 4.5, "price": 280}], "total_budget": 1860 }

第四层，前端联调。Vue3 前端把表单数据 POST 到/api/trip/plan，拿到 JSON 后渲染地图和行程卡片。这里有个真实踩坑点：地图不显示往往不是 Agent 的问题，而是前端.env里的VITE_AMAP_WEB_KEY没被引用，导致地图组件初始化失败，只有景点标记没有底图。检查前端环境变量是否以VITE_开头、是否在vite.config.ts里正确注入。

验证通过的标准我建议定三条：一是后端日志里四个 Agent 的调用顺序完整无跳过；二是返回 JSON 能被 Pydantic 模型成功解析（字段类型全对）；三是前端地图上景点标记和路线都能渲染。三条全过，才算端到端跑通。任何一条不过，都回到对应层单独复现，不要在全链路上瞎改。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

multi-agent 项目报错有个特点：错误信息往往指向表层，根因在配置。下面这几类是我和团队实际遇到频率最高的，按现象、根因、修法三段式拆开。

401 Unauthorized。现象是模型调用直接返回 401，Agent 一个都没跑起来。根因九成是 Key 问题：要么.env没加载（load_dotenv()调用位置在读取之后）、要么 Key 复制时带了空格、要么把 MCP server 的高德 Key 误填进了模型 Key 位置。修法：打印os.getenv("TAOTOKEN_API_KEY")[:8]确认前缀是sk-，确认base_url是https://taotoken.net/api而不是官网首页地址。注意 API 地址不带 UTM 参数，拼错了会 404 而不是 401，别混淆。

local proxy failed / connection refused。现象是请求发不出去，报连接失败。根因通常是 Base URL 写错或本地网络配置问题。先确认TAOTOKEN_BASE_URL完整值是https://taotoken.net/api，末尾不要多斜杠也不要少/api。如果是在容器里跑，检查容器 DNS 是否能解析外网域名。这类错误和模型无关，别去改 prompt。

reading choices 报错（'NoneType' object has no attribute 'choices'或choices为空）。现象是 Agent 跑了一半崩在解析响应处。根因有两种：一是模型返回了空 content（触发了内容过滤或超长截断），二是工具调用标记格式不合法导致模型输出异常。修法：在chat()里加防御，resp.choices为空时打印完整resp排查；同时检查 Agent prompt 里的[TOOL_CALL:...]格式是否和 HelloAgents 解析器完全一致，冒号、逗号、等号一个都不能错。

OAuth / 认证类报错。如果你在 Claude Code 或某些 CLI 工具里接入，可能会遇到 OAuth 相关提示。根因是工具默认走了官方登录流程，而你要走 API Key 模式。修法：在 settings 里显式配置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY三件套（Base URL + Key + Model ID），确保工具走 API 通道而不是交互式登录。Model ID 必须显式指定，不能留空让工具猜。

MCP server 启动后无响应。现象是tool.list_tools()卡住。根因是 server 子进程的 stdio 被阻塞，常见于 server 里 print 了调试信息污染了 stdout。修法：MCP server 的所有日志走 stderr，stdout 只留给 JSON-RPC 消息。这个坑很隐蔽，因为本地直接跑 server 看起来一切正常。

排查顺序建议固定：先单测模型通道，再单测 MCP 工具，最后全链路。每层用最小脚本复现，别一上来就调整个系统。日志里把每个 Agent 的输入输出都打出来，multi-agent 的问题定位成本主要花在「不知道是哪一层挂了」上。

6. 继续往下走：把 Key 和工具链管好，Agent 才跑得稳

写到这里，链路已经能跑通了。最后分享几个让项目从「能跑」到「好维护」的实操经验。

第一，模型分层要落到配置里，不要散在代码各处。把快速模型和推理模型的 ID 集中在一个models.toml里，Agent 初始化时按名字取，换模型只改一个文件。multi-agent 系统调参频率很高，集中配置能省大量时间。

第二，MCP 工具清单要版本化。mcp_config.json进 Git，但里面的${AMAP_API_KEY}这类占位符保持原样，真实值走环境变量。这样团队里每个人拉下来都能跑，又不会泄露密钥。

第三，给每个 Agent 加超时和重试。景点搜索和酒店搜索都是外部 API，偶发超时很正常，planner 不能因为一个 Agent 超时就整体失败。在run()外面包一层tenacity重试，超时后返回降级结果（比如「酒店信息暂不可用」），让 planner 继续整合。

第四，验证脚本要沉淀成测试。把第 4 节的三层验证写成 pytest，每次改 prompt 或换模型都跑一遍，比手动 curl 可靠得多。

如果你还没开始配 Key，从 API Keys 页面创建第一个密钥开始：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=console_api_keys 。接入细节和参数说明看文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc 。想先对比不同模型对工具调用标记的遵循度，去模型对话页试跑：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models_chat 。长期高频跑 Agent 调试的话，Coding Plan 更划算：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan 。

最后一个真实经验：multi-agent 项目的复杂度不在模型，在「数据在 Agent 之间怎么流转」。把 Pydantic 模型定义好、把每个 Agent 的输入输出边界卡死，比反复调 prompt 有效得多。工具链和 Key 通道是地基，地基稳了，上面加多少 Agent 都不慌。