1. 多智能体架构选型从单智能体瓶颈到四种协作链路多智能体架构Multi-Agent Architecture指的是把一次复杂任务拆给多个具备独立角色、独立上下文、独立工具集的智能体协同完成而不是把所有能力塞进一条 Prompt 里。它能解决四类典型问题上下文装不下、团队边界拆不开、并行查询慢、流程状态乱。适合谁适合已经跑通单智能体 工具调用、但在真实业务里开始撞墙的开发者——比如客服系统要分阶段收集信息、企业检索要同时查多个垂直库、代码助手要并行处理多个子任务。我见过太多团队一上来就搭多智能体结果调试成本翻倍、延迟飙升、token 账单失控。核心判断标准其实只有一句话先单智能体 工具卡在“上下文 / 团队 / 并行 / 流程”这四个瓶颈之一时再升级多智能体。满足任意两条就值得上专有知识塞进同一条 Prompt 会 token 膨胀能力归属清晰但 Prompt 和工具边界混乱一次请求要查多个领域并希望并行分阶段收集信息、按条件解锁能力。本文聚焦四种主流模式——Subagents中心化编排、Skills按需加载、Handoffs状态驱动切换、Router并行分发与综合给出可复制的配置片段、压测验证步骤以及如何通过统一 Key / API 通道接入方便你复现对比结果。下面先讲清楚每种模式的协作链路和代价再进入实操配置。四种模式的一句话概括Subagents 是主代理统一调度多个无状态子代理上下文隔离强、并行好代价是每轮多一次结果回流的模型调用Skills 是单代理按需加载技能包适合单代理多专长代价是技能累积进历史后容易 token 膨胀Handoffs 是对话按状态切换当前代理状态跨轮次保留适合客服和表单式分阶段流程代价是状态管理要更严谨Router 是先路由分类再并行调用多个专用代理最后综合输出适合多垂直领域检索代价是通常无状态、每次都要路由。一张表快速对齐你的需求你的需求推荐模式关键理由多领域并行执行且需要统一编排Subagents隔离强、并行好、主代理统一收口单代理多专长轻量组合与团队分工Skills按需加载、渐进披露、目录即分工有明确阶段与状态切换的顺序流程Handoffs状态跨轮保留、按条件解锁多垂直领域并行查询 综合回答Router先分类再并行、最后综合再看四种模式在四个能力维度上的强弱对比Pattern分布式开发并行化多跳串联子代理直面用户Subagents强强强弱Skills强中强强Handoffs弱弱强强Router中强弱中性能直觉上一次性单任务场景里 Skills / Handoffs / Router 通常 3 次模型调用Subagents 需要 4 次多一次结果回流重复多轮场景里 Skills / Handoffs 复用状态重复请求可节省约 40% 调用Subagents 成本更稳定但不会越聊越省多领域并行场景里 Subagents / Router 总 tokens 约 9KSkills 因上下文累积约 15KHandoffs 多为串行、常出现 7 次以上调用。2. TaoToken 前置准备统一 Key 与 API 通道接入在动手写多智能体代码之前先把模型调用通道统一。多智能体架构最怕的就是每个子代理走不同供应商、不同 Key、不同计费口径压测数据根本没法对比。TaoToken 提供统一的 API 通道一个 Key 就能调用多种模型方便你在同一套代码里切换 lead agent 和 subagent 的模型复现对比结果。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api不加 UTM注册后在控制台创建 API Key路径是 console → api-keys。拿到 Key 之后你需要准备三件套Base URL、API Key、Model ID。这三件套在后面的 Subagents、Skills、Handoffs、Router 配置里都会反复出现建议先记下来。Base URL 填https://taotoken.net/apiAPI Key 填你创建的那串Model ID 按你实际要用的模型填。如果你用的是 Claude Code 这类工具还需要配置 Anthropic 兼容的 Base URL如果是 Cline / MCP 场景配置方式略有不同但核心三件套不变。这里给一个通用的环境变量配置后面所有代码都从这里读export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_MODEL_ID你的模型ID如果你用 Python可以这样初始化客户端import os from openai import OpenAI client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) def chat(messages, modelNone): resp client.chat.completions.create( modelmodel or os.environ[TAOTOKEN_MODEL_ID], messagesmessages, ) return resp.choices[0].message.content先跑一个最小验证确认通道通了再往下写多智能体print(chat([{role: user, content: 只回复两个字通了}]))如果返回“通了”说明 Base URL、Key、Model ID 三件套没问题。如果报 401检查 Key 是否复制完整如果报 model not found检查 Model ID 拼写。这一步别跳过多智能体调试时最怕把通道问题和架构问题混在一起排查。对于长期跑编码 / Agent 任务的场景可以考虑 Coding Plan它更适合高频调用如果只是验证模型行为用模型对话页面就够了。接入文档里有各语言的完整示例遇到配置问题优先查文档。3. 四种模式可复制配置Subagents / Skills / Handoffs / Router这一节给出四种模式的可复制配置片段。为了让你能直接跑我用统一的chat函数作为底层调用每种模式只改编排逻辑。3.1 Subagents 中心化编排配置Subagents 的核心是主代理调度多个无状态子代理每个子代理只拿到自己的子任务和上下文结果回流给主代理汇总。import json def subagent(task, context): return chat([ {role: system, content: 你是子代理只完成分配给你的子任务输出简洁结果。}, {role: user, content: f任务{task}\n上下文{context}}, ]) def lead_agent(user_query): plan chat([ {role: system, content: 你是主代理把任务拆成 2-3 个子任务输出 JSON 数组。}, {role: user, content: user_query}, ]) tasks json.loads(plan) results [subagent(t, user_query) for t in tasks] return chat([ {role: system, content: 你是主代理综合子代理结果给出最终回答。}, {role: user, content: f原始问题{user_query}\n子结果{results}}, ])关键参数子代理数量建议控制在 2-4 个太多会导致回流调用次数线性上升。每个子代理的 system prompt 要写清楚边界避免它越权处理别的子任务。3.2 Skills 按需加载配置Skills 是单代理按需加载技能包技能以目录形式组织每个技能包含 Prompt、脚本、资源。SKILLS { sql: 你擅长写 SQL根据 schema 生成查询语句。, review: 你擅长代码审查指出潜在 bug 和性能问题。, doc: 你擅长写技术文档输出结构化 Markdown。, } def load_skill(name): return SKILLS.get(name, ) def skill_agent(user_query, skill_names): system 你是通用代理按需加载以下技能\n for n in skill_names: system f- {n}: {load_skill(n)}\n return chat([ {role: system, content: system}, {role: user, content: user_query}, ])注意点技能会累积进对话历史多轮之后容易 token 膨胀。建议每轮只加载当前需要的技能用完即卸。3.3 Handoffs 状态驱动切换配置Handoffs 的核心是状态机每个状态对应一个代理状态跨轮次保留。STATE {stage: collect_name, data: {}} def handoff_agent(user_input): stage STATE[stage] if stage collect_name: STATE[data][name] user_input STATE[stage] collect_issue return 已记录姓名请描述你的问题。 elif stage collect_issue: STATE[data][issue] user_input STATE[stage] resolve return chat([ {role: system, content: 你是解决代理根据收集的信息给出方案。}, {role: user, content: json.dumps(STATE[data], ensure_asciiFalse)}, ]) else: return 流程已结束如需重新开始请重置状态。状态管理要严谨每次切换前校验前置条件避免跳阶段。生产环境建议把 STATE 存到 Redis 或数据库而不是内存变量。3.4 Router 并行分发与综合配置Router 先分类再并行调用多个专用代理最后综合输出。from concurrent.futures import ThreadPoolExecutor def route(query): raw chat([ {role: system, content: 把问题分类到以下领域之一tech, finance, legal。只输出领域名。}, {role: user, content: query}, ]) return raw.strip() def domain_agent(domain, query): return chat([ {role: system, content: f你是 {domain} 领域专家简洁回答。}, {role: user, content: query}, ]) def router_agent(query): domains [tech, finance, legal] with ThreadPoolExecutor(max_workers3) as ex: results list(ex.map(lambda d: domain_agent(d, query), domains)) return chat([ {role: system, content: 综合以下多领域结果给出统一回答。}, {role: user, content: f问题{query}\n结果{results}}, ])Router 通常无状态每次都要路由。如果需要记忆可以把 Router 包进一个有状态的对话代理里。4. 验证请求与压测对比四种模式的延迟与 token配置写完接下来是压测验证。我建议用同一组问题分别跑四种模式记录三个指标总延迟、模型调用次数、总 token 消耗。先写一个计时装饰器import time def timed(fn): def wrapper(*args, **kwargs): start time.time() result fn(*args, **kwargs) cost time.time() - start print(f{fn.__name__} 耗时 {cost:.2f}s) return result return wrapper然后准备一组测试问题覆盖单任务、多轮、多领域三类场景questions [ 帮我写一个 Python 快速排序, 我想了解企业检索系统的架构设计, 同时分析这段代码的性能和安全性, ]分别调用四种模式记录结果。实测下来一次性单任务场景里 Skills / Handoffs / Router 通常 3 次模型调用Subagents 4 次多领域并行场景里 Subagents / Router 总 tokens 约 9KSkills 因上下文累积约 15KHandoffs 多为串行、常出现 7 次以上调用。如果你要复现这个对比建议固定 Model ID 和 temperature避免模型差异干扰结果。压测时先用小样本跑通再放大到 20-50 条问题取平均值。验证请求是否成功除了看返回内容还要看 HTTP 状态码。可以在chat函数里加一层日志def chat_with_log(messages, modelNone): resp client.chat.completions.create( modelmodel or os.environ[TAOTOKEN_MODEL_ID], messagesmessages, ) print(usage:, resp.usage) return resp.choices[0].message.contentresp.usage会给出 prompt_tokens、completion_tokens、total_tokens这是你对比四种模式 token 消耗的直接依据。5. 本篇常见错排查401 / local proxy failed / reading choices / OAuth多智能体调试时报错往往集中在通道层和解析层。下面按真实报错逐一排查。401 Unauthorized最常见。检查 API Key 是否复制完整、是否有多余空格、是否用了过期 Key。如果你把 Key 写进代码里确认环境变量读取正确。用echo $TAOTOKEN_API_KEY确认值存在。local proxy failed通常是本地网络配置问题。检查 Base URL 是否写成https://taotoken.net/api不要多加斜杠或路径。如果你在容器里跑确认容器能访问外网。reading choices 报错一般是返回结构不符合预期比如模型返回了非 JSON 内容但代码直接json.loads。解决方法是先打印原始返回确认结构再解析。Subagents 的 plan 解析最容易踩这个坑建议加 try/except 兜底。OAuth 相关报错如果你用 Claude Code 或 Codex 这类工具OAuth 配置和 API Key 配置是两套。确认你用的是 API Key 模式Base URL 填https://taotoken.net/api。Codex 的 auth.json 里要写全三件套Base URL、Key、Model ID。如果你用 CC Switch 或 Cline MCP配置里同样要写全三件套。CC Switch 的配置片段示例{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model_id: 你的模型ID }Cline MCP 的 settings 片段{ mcpServers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: 你的模型ID } } }Codex 的 auth.json{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的模型ID }排查顺序建议先确认三件套齐全再确认网络可达最后确认返回结构。别一上来就怀疑架构代码八成问题在通道层。6. 选型落地用五个问题定方向并接入统一通道回到选型本身。你可以用五个问题快速定方向并行还是串行需要状态吗要隔离上下文吗子模块要直面用户吗是否多团队共建如果并行且需要统一编排选 Subagents如果单代理多专长、轻量组合选 Skills如果有明确阶段和状态切换选 Handoffs如果多垂直领域并行查询加综合选 Router。三条落地建议先把单智能体 工具做扎实观测 token、延迟、失败类型别本末倒置卡在上下文与并行时优先看 Subagents / Router卡在流程与体验时优先看 Handoffs卡在轻量多专长时优先看 Skills。接入统一通道后你可以在同一套代码里切换 lead agent 和 subagent 的模型压测数据才有可比性。API Key 在 https://taotoken.net/api-keys 创建接入文档在 https://taotoken.net/doc模型对话验证在 https://taotoken.net/chat长期编码 / Agent 任务用 Coding Plan。先把通道跑通再按上面的配置片段逐个复现四种模式对比延迟和 token选型就不再是拍脑袋。