1. 单Agent和多Agent架构选型先跑通再谈架构单Agent和多Agent架构选型本质上是在问一个问题一个模型实例加一套工具循环能不能把这件事干完如果能就别急着拆成多个角色互相喊话。我见过太多项目任务本身只是读三个文件、改一处配置、跑一次测试却硬生生拆成 Planner、Coder、Reviewer、Tester 四个 Agent结果调用链路从 1 条变成 7 条Token 消耗翻了好几倍调试时连是哪一步把参数传错了都定位不到。单Agent指的是一个模型实例配合一组工具读写文件、执行命令、检索在一个循环里完成思考—调用—观察—再思考。多Agent则是把任务拆给多个模型实例每个实例有独立角色和上下文通过消息传递或共享状态协作。适合谁如果你在做 AI 工作流、自动化脚本、代码助手、数据分析管道这两个词你一定绕不开。判断标准其实很朴素单Agent的瓶颈通常出现在三个地方——上下文窗口装不下、单条推理路径一旦走错就全盘失败、串行执行太慢。只有当你确认撞上了这三个硬瓶颈之一并且拆成多Agent后收益能覆盖额外成本才值得引入多Agent。Anthropic 的工程实践里有一条被反复引用的原则默认从单Agent开始只有当引入复杂性可以明显改善结果时才去引入它。这篇文章不空谈架构我用同一个任务——扫描一个项目目录找出所有 TODO 注释汇总成一份带文件路径和行号的报告——分别用单Agent和多Agent实现并且用 TaoToken 的统一 Key 把两种架构都跑通。这样你能直观看到调用链路、成本和效果的差异也能直接复制配置去验证。为什么强调统一 Key因为对比两种架构时最怕的就是变量不统一单Agent用 A 家的 Key多Agent用 B 家的 Key最后成本差异到底是架构带来的还是模型价格带来的根本说不清。TaoToken 提供 OpenAI 兼容接口一个 Key 就能切换不同模型正好适合做这种对照实验。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后拿到 Key后面两种架构共用同一个 Base URL 和 Key对比才有意义。2. TaoToken 统一 Key 前置配置Base URL、Key 与 Model ID 三件套在写任何 Agent 代码之前先把接入层配好。TaoToken 的 API 地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 OpenAI SDK 的 base_url 使用。你需要准备三样东西我把它叫做三件套Base URL、API Key、Model ID。这三件套在单Agent和多Agent里完全一致这也是做对照实验的前提。先说 Key 怎么拿。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key复制出来。这个 Key 只显示一次建议直接写进环境变量不要硬编码在代码里。我试过把它写进.env文件然后被 git 提交上去虽然及时删了但那种心惊肉跳的感觉不想再来第二次。然后是 Model ID。TaoToken 支持多种模型你在控制台或模型列表里能看到可用的模型标识。做 Agent 任务时我一般选一个推理能力够用、价格适中的模型比如带工具调用能力的通用模型。Model ID 要填准确写错了会直接报模型不存在。配置方式有两种选你顺手的。第一种是环境变量适合本地开发和 CIexport TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODEL你的ModelID第二种是写进配置文件。如果你用 Claude Code 或类似的编码工具配置通常放在~/.claude/settings.json或项目级的.claude/settings.json。这里给一个可复制的 JSON 片段路径和字段名按你实际工具的要求来{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: 你的ModelID } }如果你用的是 Cline 或带 MCP 的客户端配置里同样要写全三件套。以 Cline 的 MCP 配置为例Base URL 填https://taotoken.net/apiAPI Key 填你的 KeyModel ID 填模型标识。三件套缺一不可少一个就会在请求时失败。注意Base URL 末尾不要多加/v1或斜杠除非你的客户端明确要求。TaoToken 的兼容层会处理路径拼接多写反而容易 404。配好之后先用一个最小请求验证连通性别等 Agent 跑起来才发现 Key 是错的。下面这段 Python 用 OpenAI SDK 发一个最简单的对话请求from openai import OpenAI import os client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL], messages[{role: user, content: 只回复两个字连通}], ) print(resp.choices[0].message.content)如果打印出连通说明三件套配置正确可以进入下一步。如果报错先看第 5 节的排查清单那里列了最常见的几种报错和对应原因。3. 可复制配置单Agent与多Agent共用同一套接入层这一节是全文的核心我把两种架构的完整代码都放出来它们共用同一个 client 初始化逻辑只有编排方式不同。这样你复制过去就能跑也能清楚看到差异到底在哪。先建一个公共模块llm_client.py把三件套封装好import os from openai import OpenAI def get_client(): return OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) MODEL os.environ[TAOTOKEN_MODEL]3.1 单Agent实现一个循环干完所有事单Agent的思路是给模型一个系统提示告诉它有哪些工具然后让它自己决定调用顺序。工具包括list_files、read_file、search_todo。模型在循环里不断调用工具直到它认为可以输出最终报告。import json from llm_client import get_client, MODEL client get_client() TOOLS [ { type: function, function: { name: list_files, description: 列出目录下的所有文件路径, parameters: { type: object, properties: {path: {type: string}}, required: [path], }, }, }, { type: function, function: { name: read_file, description: 读取指定文件的全部内容, parameters: { type: object, properties: {path: {type: string}}, required: [path], }, }, }, ] def execute_tool(name, args): if name list_files: import os result [] for root, _, files in os.walk(args[path]): for f in files: result.append(os.path.join(root, f)) return json.dumps(result[:200]) if name read_file: with open(args[path], r, encodingutf-8, errorsignore) as f: return f.read()[:4000] return unknown tool def run_single_agent(task_dir): messages [ {role: system, content: 你是一个代码分析助手。用工具扫描目录找出所有包含 TODO 的文件输出 JSON 列表每项含 path 和 line。}, {role: user, content: f扫描目录{task_dir}}, ] for step in range(15): resp client.chat.completions.create( modelMODEL, messagesmessages, toolsTOOLS, ) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content for call in msg.tool_calls: args json.loads(call.function.arguments) result execute_tool(call.function.name, args) messages.append({ role: tool, tool_call_id: call.id, content: result, }) return 达到最大步数未完成单Agent的调用链路是线性的一次请求 → 可能多个工具调用 → 再请求 → 直到输出。所有上下文都在一个 messages 列表里调试时打印这个列表就能看到完整轨迹。3.2 多Agent实现拆成扫描、分析、汇总三个角色多Agent的思路是把任务拆成三个子任务Scanner 负责列出文件Analyzer 负责逐个读文件找 TODOReporter 负责汇总。每个 Agent 有独立的 messages通过一个协调函数传递中间结果。def run_scanner(task_dir): messages [ {role: system, content: 你负责列出目录下所有文件只输出文件路径列表每行一个。}, {role: user, content: f目录{task_dir}}, ] resp client.chat.completions.create(modelMODEL, messagesmessages, toolsTOOLS) msg resp.choices[0].message if msg.tool_calls: args json.loads(msg.tool_calls[0].function.arguments) return json.loads(execute_tool(list_files, args)) return [] def run_analyzer(file_path): messages [ {role: system, content: 读取文件找出所有 TODO 注释输出 JSON 数组每项含 line 和 text。}, {role: user, content: f文件{file_path}}, ] resp client.chat.completions.create(modelMODEL, messagesmessages, toolsTOOLS) msg resp.choices[0].message if msg.tool_calls: args json.loads(msg.tool_calls[0].function.arguments) content execute_tool(read_file, args) messages.append(msg) messages.append({role: tool, tool_call_id: msg.tool_calls[0].id, content: content}) resp2 client.chat.completions.create(modelMODEL, messagesmessages) return resp2.choices[0].message.content return [] def run_multi_agent(task_dir): files run_scanner(task_dir) results [] for f in files[:20]: results.append({file: f, todos: run_analyzer(f)}) messages [ {role: system, content: 把以下各文件的 TODO 分析结果汇总成一份 JSON 报告。}, {role: user, content: json.dumps(results, ensure_asciiFalse)}, ] resp client.chat.completions.create(modelMODEL, messagesmessages) return resp.choices[0].message.content多Agent的调用链路是Scanner 1 次请求Analyzer 每个文件 2 次请求一次决定读文件一次分析内容Reporter 1 次请求。如果目录里有 20 个文件总请求数就是 1 40 1 42 次而单Agent可能 5 到 8 次就结束了。这就是成本差异的来源。3.3 两种架构的配置对照维度单Agent多AgentBase URLhttps://taotoken.net/apihttps://taotoken.net/apiAPI Key同一个 Key同一个 KeyModel ID同一个模型同一个模型请求次数5–8 次40 次上下文单一 messages 列表每个 Agent 独立调试难度低看一个列表高要追踪多个列表三件套完全一致唯一变量是编排方式。这样你跑出来的成本和效果差异才能归因到架构本身。4. 验证请求与成功结果两种架构跑同一个任务配置写好了接下来实际跑一遍。我准备了一个测试目录里面有 5 个 Python 文件其中 3 个文件里埋了 TODO 注释。先跑单Agentresult run_single_agent(./test_project) print(result)单Agent的输出大致是这样[ {path: ./test_project/a.py, line: 12, text: TODO: 补充异常处理}, {path: ./test_project/c.py, line: 5, text: TODO: 替换硬编码路径}, {path: ./test_project/e.py, line: 30, text: TODO: 增加单元测试} ]整个过程请求了 6 次Token 消耗在可接受范围内耗时约 15 秒。调用链路清晰模型先列文件再挑几个文件读最后汇总。如果结果不对我打印 messages 就能看到它在哪一步读错了文件。再跑多Agentresult run_multi_agent(./test_project) print(result)多Agent的输出格式类似但过程完全不同。Scanner 先列出 5 个文件Analyzer 对每个文件发起 2 次请求Reporter 最后汇总。总请求 1 10 1 12 次耗时约 40 秒Token 消耗明显更高。效果上多Agent因为每个文件独立分析漏报率略低但差异在这个小任务上并不明显。关键观察在这个任务规模下单Agent的性价比明显更高。多Agent的优势要等到文件数量上百、或者需要多角度交叉验证时才会体现。你可以把测试目录换成你自己的项目调整文件数量观察请求次数和耗时的变化曲线。当单Agent开始因为上下文装不下而漏文件时就是考虑多Agent的信号。验证时还有一个细节两种架构都用了同一个 Model ID所以输出风格一致对比才公平。如果你在单Agent里用便宜模型、多Agent里用贵模型那成本差异就混入了模型因素结论不可信。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth跑 Agent 时最容易在接入层翻车我把几种真实报错和原因列出来对照着查。401 UnauthorizedKey 错了、过期了或者环境变量没读到。先确认echo $TAOTOKEN_API_KEY有值再确认 Key 没有多余空格。如果用的是配置文件检查字段名是不是ANTHROPIC_AUTH_TOKEN或api_key不同客户端字段名不一样写错了就等于没配。local proxy failed / connection refusedBase URL 写错了或者本地网络到不了。确认地址是https://taotoken.net/api不要写成http也不要多加/v1。如果你在容器里跑检查容器能不能访问外网。reading choices 相关报错通常是响应结构和你解析的字段不匹配。比如你按resp[choices]解析但实际返回的是对象或者模型返回了 tool_calls你却在读 content。打印完整响应体看清楚结构再改解析代码。OAuth 相关报错如果你用的是 Claude Code 这类工具它可能默认走 OAuth 登录而不是 API Key。需要在配置里显式指定用 API Key 模式把三件套写全。Base URL、Key、Model ID 一个都不能少缺了就会回退到 OAuth 流程然后失败。还有一个隐蔽的坑多Agent里每个 Agent 都新建 client 实例如果 Key 读取逻辑写在实例化时而环境变量在某个 Agent 里没传到就会只有部分 Agent 报 401。建议把 client 做成单例或者统一从llm_client.py导入。排查顺序建议先跑第 2 节的最小请求确认三件套通再跑单Agent确认工具调用通最后跑多Agent确认多实例共享配置没问题。一层层来比一上来就跑复杂架构高效得多。6. 按场景做选择从单Agent起步用数据决定是否拆分回到最初的问题单Agent和多Agent怎么选我的建议是默认从单Agent开始把它当作基线。只有当你在真实任务上观察到以下信号之一才考虑拆分上下文窗口频繁溢出、单条推理路径的错误率无法接受、串行执行时间超出业务要求。拆分之后一定要用同一套三件套做对照实验量化收益。如果多Agent带来的质量提升不足以覆盖翻倍的 Token 成本和调试复杂度那就退回单Agent把精力花在优化提示词和工具设计上。架构不是越复杂越好能稳定跑通、容易维护的才是好架构。如果你要长期跑编码类 Agent 或自动化工作流可以了解下 Coding Plan它更适合高频、持续的调用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先验证模型效果可以直接在模型对话里试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。把三件套配好先跑单Agent再决定要不要拆。