企业官网建设流程全解析

1. 从单 Agent 到 multi agent：为什么 tool use 是分水岭

OpenAI Agent 从入门到精通，绕不开一个核心能力：tool use。你可以把 Agent 理解成一个会自己查资料、自己动手的实习生，而 tool use 就是他手里的工具箱。没有工具箱，他只能靠记忆回答问题；有了工具箱，他能查天气、读文件、跑代码、调接口，甚至指挥另一个实习生干活。这就是单 Agent 和 multi agent 的本质区别。

我见过太多开发者卡在同一个地方：单 Agent 跑通了，一到 multi agent 就乱套。要么是工具调用返回格式对不上，要么是多个 Agent 之间互相等待死锁，要么是 Key 管理一团糟——每个模型、每个工具都要单独配一套凭证。这篇文章就是来解决这些问题的。

先说清楚适合谁看：如果你已经能写一个简单的 OpenAI function calling demo，想进一步搞懂任务拆解、工具编排、多 Agent 协作，那这篇就是为你写的。如果你还没跑通过任何 Agent，也没关系，我会从最基础的配置开始，每一步都给可复制的代码。

整个进阶路径可以拆成三个阶段。第一阶段是单 Agent + 单工具，理解 tool use 的基本闭环：模型决定调用哪个工具、传什么参数、拿到结果后怎么继续推理。第二阶段是单 Agent + 多工具，这时候你会遇到工具描述冲突、参数校验失败、调用顺序错乱等问题。第三阶段是 multi agent，把一个大任务拆成多个子任务，每个 Agent 专注一件事，通过统一的调度层协调。

这三个阶段里，最容易被低估的是第二阶段。很多人以为多加几个工具就行了，实际上工具一多，模型选错工具的概率会明显上升。OpenAI 在访谈里提到，目前 Agent 可调用的工具数量在 10 个量级，下一步要 Scale 到 100 个量级。工具越多，对工具描述的准确性、参数 schema 的严谨性要求就越高。

还有一个现实问题：当你同时用 OpenAI、Claude、国产模型来做不同 Agent 时，每家 API 的鉴权方式、请求格式、返回结构都不一样。如果每个 Agent 都单独维护一套 Key 和 Base URL，调试成本会非常高。我试过用统一 Key 层来管理，后面会详细讲怎么配。

先明确一个概念：tool use 不是简单的函数调用。模型需要理解工具的语义、判断什么时候该用、从上下文里提取参数、处理返回结果、决定下一步。这整个链条里任何一环出问题，Agent 就会卡住或者跑偏。所以验证动作很重要——本地跑一次完整任务链，确认每个 Agent 都按预期调用了工具并返回了结果。

2. TaoToken 统一 Key：多模型 Agent 的前置配置

做 multi agent 最烦的事情之一，就是每个 Agent 可能用不同的模型。分诊 Agent 用便宜快的小模型，推理 Agent 用强模型，工具调用 Agent 可能又换一个。如果每个都去单独申请 Key、单独配环境变量，代码里到处是 if else 判断用哪个 Key，维护起来很痛苦。

TaoToken 解决的就是这个问题：一个 Key 打通多个模型，Base URL 统一，请求格式兼容 OpenAI 标准。这样你在写 Agent 代码时，只需要切换 model 参数，不用改鉴权逻辑。

先拿到 Key。访问 https://taotoken.net/api-keys 创建一个 API Key，复制保存好。注意这个 Key 只在创建时显示一次，丢了就得重新建。

然后确认你的 Base URL。TaoToken 的 API 端点是：

https://taotoken.net/api

注意不要在后面加/v1，SDK 会自动处理路径。如果你用的是 OpenAI 官方 SDK，配置方式如下：

from openai import OpenAI client = OpenAI( api_key="sk-你的TaoToken Key", base_url="https://taotoken.net/api" )

如果你用环境变量管理，可以这样：

export OPENAI_API_KEY="sk-你的TaoToken Key" export OPENAI_BASE_URL="https://taotoken.net/api"

对于 Claude Code 这类工具，配置方式略有不同。Claude Code 使用 Anthropic 的接口规范，需要在 settings 里指定 Base URL 和 Key。具体路径是~/.claude/settings.json：

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

如果你用 Cline 或者 Roo Code 这类 VS Code 插件，配置在插件的 settings 里。以 Cline 为例，在 API Provider 里选 OpenAI Compatible，然后填：

• Base URL:https://taotoken.net/api
• API Key:sk-你的TaoToken Key
• Model ID: 比如gpt-4o或claude-sonnet-4-20250514

这里有个坑要注意：不同工具对 Base URL 的拼接方式不一样。有的工具会自动加/v1/chat/completions，有的不会。如果遇到 404，先检查 Base URL 是不是多加了或者少加了路径。TaoToken 的文档里有各工具的详细配置示例，可以对照检查。

对于 Codex 这类工具，配置在~/.codex/auth.json：

{ "openai_api_key": "sk-你的TaoToken Key", "base_url": "https://taotoken.net/api" }

统一 Key 的好处不只是省事。当你做 multi agent 时，所有 Agent 共享同一个 Key 池，计费、限流、日志都在一个地方看。哪个 Agent 消耗了多少 token，哪个工具调用最频繁，一目了然。如果每个 Agent 单独一套 Key，排查问题时要来回切换后台，效率很低。

还有一个实际场景：你本地跑 Agent demo 时用一套 Key，部署到服务器时又换一套。如果代码里硬编码了 Key，迁移时容易漏改。用环境变量 + 统一 Base URL 的方式，迁移时只需要改环境变量，代码不用动。

配置完成后，先跑一个最简单的请求验证连通性：

response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "回复 OK"}] ) print(response.choices[0].message.content)

如果输出 OK，说明 Key 和 Base URL 都配对了。如果报 401，检查 Key 是否复制完整；如果报 404，检查 Base URL 是否有多余路径；如果报 model not found，检查模型名是否正确。

3. 可复制配置：tool use 与 multi agent 编排片段

这一节给可直接复制的配置和代码。先讲 tool use 的完整闭环，再讲 multi agent 的编排。

3.1 单 Agent + tool use 最小闭环

定义一个查天气的工具：

tools = [ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的当前天气", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，如北京、上海" } }, "required": ["city"] } } } ]

发起请求：

messages = [{"role": "user", "content": "北京今天天气怎么样？"}] response = client.chat.completions.create( model="gpt-4o", messages=messages, tools=tools, tool_choice="auto" ) tool_call = response.choices[0].message.tool_calls[0] print(tool_call.function.name) # get_weather print(tool_call.function.arguments) # {"city": "北京"}

拿到工具调用后，执行本地函数并把结果塞回对话：

import json def get_weather(city): # 模拟返回，实际替换为真实 API return json.dumps({"city": city, "temp": "22°C", "condition": "晴"}) result = get_weather(**json.loads(tool_call.function.arguments)) messages.append(response.choices[0].message) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": result }) final = client.chat.completions.create( model="gpt-4o", messages=messages, tools=tools ) print(final.choices[0].message.content)

这就是 tool use 的最小闭环。关键点：tool_call_id必须和请求里的 id 对应，否则模型不知道哪个结果对应哪个调用。

3.2 multi agent 编排配置

multi agent 的核心是任务拆解和调度。下面是一个三 Agent 协作的配置示例：分诊 Agent 判断任务类型，检索 Agent 查资料，总结 Agent 出结果。

AGENTS = { "triage": { "model": "gpt-4o-mini", "system": "你是一个分诊助手。判断用户问题属于哪类：weather、search、general。只返回类别名。" }, "search": { "model": "gpt-4o", "system": "你是一个检索助手。根据用户问题调用搜索工具，返回原始结果。", "tools": ["web_search"] }, "summary": { "model": "gpt-4o", "system": "你是一个总结助手。把检索结果整理成简洁的中文回答。" } }

调度逻辑：

def run_multi_agent(user_input): # Step 1: 分诊 triage_resp = client.chat.completions.create( model=AGENTS["triage"]["model"], messages=[ {"role": "system", "content": AGENTS["triage"]["system"]}, {"role": "user", "content": user_input} ] ) category = triage_resp.choices[0].message.content.strip() # Step 2: 根据类别路由 if category == "search": search_resp = client.chat.completions.create( model=AGENTS["search"]["model"], messages=[ {"role": "system", "content": AGENTS["search"]["system"]}, {"role": "user", "content": user_input} ], tools=search_tools ) # 处理 tool call... raw_result = "检索到的原始内容" else: raw_result = "无需检索" # Step 3: 总结 summary_resp = client.chat.completions.create( model=AGENTS["summary"]["model"], messages=[ {"role": "system", "content": AGENTS["summary"]["system"]}, {"role": "user", "content": f"问题：{user_input}\n资料：{raw_result}"} ] ) return summary_resp.choices[0].message.content

这个结构的好处是每个 Agent 的 prompt 独立调试。分诊 Agent 改错了，不影响检索和总结。如果用一个 Agent 干所有事，改一个 prompt 可能导致整个流程崩掉。

3.3 工具注册表配置

当工具有多个时，建议用一个注册表管理：

TOOL_REGISTRY = { "get_weather": { "fn": get_weather, "schema": { "type": "function", "function": { "name": "get_weather", "description": "查询城市天气", "parameters": { "type": "object", "properties": { "city": {"type": "string"} }, "required": ["city"] } } } }, "web_search": { "fn": web_search, "schema": { "type": "function", "function": { "name": "web_search", "description": "搜索互联网", "parameters": { "type": "object", "properties": { "query": {"type": "string"} }, "required": ["query"] } } } } }

这样新增工具只需要往注册表里加一项，调度代码不用改。

4. 验证请求：本地跑通完整任务链

配置写完了，必须验证。验证的目标是：本地运行一次完整任务链，确认各 Agent 按预期调用工具并返回结果。

4.1 验证单 Agent tool use

先跑一个最小验证脚本：

import json from openai import OpenAI client = OpenAI( api_key="sk-你的TaoToken Key", base_url="https://taotoken.net/api" ) def get_weather(city): return json.dumps({"city": city, "temp": "22°C", "condition": "晴"}) tools = [{ "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的当前天气", "parameters": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"] } } }] messages = [{"role": "user", "content": "上海天气"}] resp = client.chat.completions.create( model="gpt-4o", messages=messages, tools=tools ) msg = resp.choices[0].message if msg.tool_calls: tc = msg.tool_calls[0] print(f"工具名: {tc.function.name}") print(f"参数: {tc.function.arguments}") result = get_weather(**json.loads(tc.function.arguments)) messages.append(msg) messages.append({ "role": "tool", "tool_call_id": tc.id, "content": result }) final = client.chat.completions.create( model="gpt-4o", messages=messages, tools=tools ) print(f"最终回答: {final.choices[0].message.content}") else: print("模型没有调用工具，直接回答:", msg.content)

预期输出：工具名 get_weather，参数包含 city，最终回答里包含天气信息。如果模型没调用工具，检查 tool_choice 是否设为 auto，或者工具描述是否足够清晰。

4.2 验证 multi agent 任务链

跑一个完整的三 Agent 流程：

def test_multi_agent(): user_input = "帮我查一下北京天气，然后总结成一句话" # 分诊 triage = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "判断任务类型：weather 或 general。只返回类别名。"}, {"role": "user", "content": user_input} ] ) category = triage.choices[0].message.content.strip() print(f"[分诊结果] {category}") # 工具调用 if "weather" in category: tool_resp = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": user_input}], tools=tools ) tc = tool_resp.choices[0].message.tool_calls[0] print(f"[工具调用] {tc.function.name}({tc.function.arguments})") weather_data = get_weather(**json.loads(tc.function.arguments)) print(f"[工具返回] {weather_data}") # 总结 summary = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": "把天气数据总结成一句话。"}, {"role": "user", "content": weather_data} ] ) print(f"[最终输出] {summary.choices[0].message.content}") test_multi_agent()

预期输出类似：

[分诊结果] weather [工具调用] get_weather({"city": "北京"}) [工具返回] {"city": "北京", "temp": "22°C", "condition": "晴"} [最终输出] 北京当前天气晴，气温22°C。

如果中间任何一步输出不符合预期，就针对那一步单独调试。分诊错了就改分诊 prompt；工具没调用就检查工具 schema；总结不对就改总结 prompt。

4.3 验证多工具切换

再加一个工具，验证模型能否正确选择：

tools.append({ "type": "function", "function": { "name": "get_time", "description": "查询当前时间", "parameters": {"type": "object", "properties": {}} } }) # 测试：问时间 resp = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "现在几点了？"}], tools=tools ) print(resp.choices[0].message.tool_calls[0].function.name) # 预期输出：get_time

如果模型选了 get_weather，说明工具描述有歧义，需要把 description 写得更明确。

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

这一节对照真实报错，给出排查路径。

5.1 401 Unauthorized

报错原文：

openai.AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API key', 'type': 'invalid_request_error'}}

原因通常是 Key 不对。检查步骤：

第一，确认 Key 复制完整，没有多余空格。TaoToken 的 Key 以sk-开头，后面是一串字符。如果复制时漏了尾部，就会 401。

第二，确认 Base URL 配对。如果你用的是 TaoToken 的 Key，Base URL 必须是https://taotoken.net/api。如果 Base URL 写成了其他地址，Key 自然验证不过。

第三，检查环境变量是否生效。有时候你在终端 export 了，但 IDE 里没继承。可以在代码里打印os.environ.get("OPENAI_API_KEY")确认。

第四，如果用的是 Claude Code，检查~/.claude/settings.json里的ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL是否都配了。只配 Key 不配 Base URL，请求会发到默认地址，导致 401。

5.2 local proxy failed

报错原文：

APIConnectionError: Connection error: local proxy failed

这个报错通常和网络环境有关。检查步骤：

第一，确认没有配置系统级代理。有些工具会读取HTTP_PROXY或HTTPS_PROXY环境变量，如果这些变量指向了一个不可用的地址，就会报 local proxy failed。可以临时 unset：

unset HTTP_PROXY unset HTTPS_PROXY

第二，检查防火墙或安全软件是否拦截了请求。可以先用 curl 测试连通性：

curl -X POST https://taotoken.net/api/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}]}'

如果 curl 能通但代码不通，说明是代码里的代理配置问题。

第三，如果用的是公司网络，可能有出口限制。这种情况需要联系网络管理员，或者换一个网络环境测试。

5.3 reading choices 报错

报错原文：

KeyError: 'choices'

或者：

IndexError: list index out of range

这个报错说明返回结构里没有 choices 字段。原因通常是：

第一，请求本身失败了，返回的是错误信息而不是正常响应。先打印完整 response 看看：

print(response.model_dump_json(indent=2))

第二，模型名写错了。如果 model 参数传了一个不存在的模型，有些接口会返回错误结构。检查模型名是否在 TaoToken 支持的列表里。

第三，流式和非流式混用。如果你用了stream=True，返回的是迭代器，不能直接取choices[0]。需要遍历：

for chunk in response: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="")

5.4 OAuth 相关报错

报错原文：

OAuth error: invalid_grant

或者：

Token refresh failed

这类报错通常出现在 Claude Code 或 Codex 这类需要 OAuth 的工具里。检查步骤：

第一，确认你用的是 API Key 模式而不是 OAuth 模式。有些工具默认走 OAuth 登录，但如果你要用 TaoToken 的 Key，需要在配置里显式指定 API Key 模式。

第二，对于 Claude Code，检查~/.claude/settings.json里是否同时配了ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL。如果只配了 Key 没配 Base URL，工具可能会尝试 OAuth 流程。

第三，对于 Codex，检查~/.codex/auth.json里的openai_api_key和base_url是否都正确。如果 auth.json 里还有旧的 OAuth token，可能会冲突。可以删掉重新生成。

第四，如果报错里提到refresh_token，说明工具在尝试刷新 OAuth token。这种情况下，要么完成 OAuth 流程，要么切换到 API Key 模式。

5.5 工具调用参数解析失败

报错原文：

json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes

这个报错说明模型返回的 arguments 不是合法 JSON。原因通常是模型在参数里加了额外内容，比如 markdown 代码块标记。处理方式：

import json raw_args = tc.function.arguments # 去掉可能的 markdown 标记 if raw_args.startswith("```"): raw_args = raw_args.strip("`").strip() if raw_args.startswith("json"): raw_args = raw_args[4:].strip() args = json.loads(raw_args)

更稳妥的方式是在工具描述里明确要求返回纯 JSON，不要加任何标记。

6. 语义一致 CTA：从 demo 到生产的下一步

跑通上面的验证脚本后，你已经有了一个可工作的 multi agent demo。下一步是根据实际场景调整。

如果你主要做模型对话类应用，比如客服 Agent、问答 Agent，可以先在模型对话页面测试不同模型的效果，找到性价比最高的组合。访问 https://taotoken.net/model-chat 可以直接对比不同模型的输出。

如果你要做长期编码类 Agent，比如自动修 bug、自动写测试，建议了解一下 Coding Plan。这类场景对模型的代码理解和工具调用能力要求更高，需要更稳定的调用配额。详情看 https://taotoken.net/coding-plan。

如果你需要管理多个项目的 Key，或者给团队成员分配不同的权限，可以在控制台里创建多个 Key 并设置限额。地址是 https://taotoken.net/console。

接入文档里有各语言 SDK 的详细示例和错误码说明，遇到问题可以先查文档：https://taotoken.net/doc。

最后给一个实用建议：multi agent 的调试不要一上来就搞三四个 Agent。先用两个 Agent 跑通，确认调度逻辑没问题，再逐步加。每加一个 Agent，就单独验证它的输入输出。这样出问题时容易定位是哪个环节的错。另外，工具描述要写得像给新人看的文档，越具体越好。模型选错工具，十有八九是描述太模糊。