大模型进阶：收藏 | Subagent与Agent Team，解锁多Agent协作新思路

1. 从单 Agent 失焦说起多 Agent 协作到底解决什么问题单 Agent 处理复杂任务时最容易出现的情况不是“不会做”而是“做到一半忘了主线”。我试过让一个 Agent 从读代码一路做到补测试前 20 轮还挺顺到第 30 轮它开始把前面确认过的接口字段改回去理由是“根据最新日志推断”。这就是上下文过载导致的失焦测试日志几千行、代码搜索结果几十个文件、依赖分析带出一堆无关内容全部堆进同一个对话窗口主线的权重被稀释了。多 Agent 协作的核心思路是把“一个大脑扛所有事”改成“一个主线大脑 若干专项执行者”。这里面有两种常见形态Subagent子代理主 Agent 把边界清晰的小任务派出去Subagent 干完只回传摘要。主 Agent 的上下文始终保持干净只保留决策所需的关键结论。典型场景是查代码、跑测试、读文档、做单点 Review。Agent Team代理团队多个 Agent 围绕同一个目标协作各自有角色分工可以交换信息、互相质疑、互相补充。典型场景是复杂 Bug 排查、跨模块开发、方案设计、大型重构。两者的选择标准其实一句话就能判断任务边界清楚、做完只需返回结果用 Subagent任务需要多角色持续协作、互相验证用 Agent Team。这篇文章要解决的是工程化落地问题怎么把这两种协作模式在自己的项目里跑起来。我会给出可复制的 Agent Team 配置模板、Subagent 调度示例以及本地运行验证的完整步骤。整套流程通过 TaoToken 提供的统一 API 接入Base URL 和 Key 的配置方式在第三节会写清楚。适合谁看已经用过单 Agent 做编码辅助、但遇到上下文混乱问题的开发者想在自己的工具链里加入多 Agent 协作、但不知道从哪下手的工程师以及需要一套可复现配置模板、不想从零设计编排逻辑的团队。前置知识只需要你会用命令行、能看懂 JSON 配置、对 API 调用有基本概念。不需要你之前搭过 Agent 框架。2. TaoToken 前置准备统一接入多模型为 Agent Team 提供调度底座多 Agent 协作落地时第一个卡点往往不是编排逻辑而是模型接入。Agent Team 里不同角色可能适合不同模型规划角色用推理强的实现角色用代码能力好的Review 角色用长上下文稳定的。如果每个模型都要单独配一套 Key 和 Base URL配置管理会变得很碎。TaoToken 在这里的作用是提供一个统一的 API 入口让你用同一套 Base URL 和 Key 调用不同模型。这样 Agent Team 的配置文件里模型切换只需要改 Model ID不用动接入层。2.1 获取 API Key 与确认 Base URL进入控制台后创建 API Key建议按项目或按 Agent 角色分别创建方便后续做用量追踪和权限隔离。创建完成后你会拿到一个以sk-开头的 Key。接入地址统一使用https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 填入配置即可。模型对话、Coding Plan、控制台、API Keys 管理、接入文档、Claude Code 相关配置都可以从官网入口进入对应页面。2.2 确认可用 Model ID在模型对话页面或接入文档里可以查到当前支持的 Model ID 列表。Agent Team 配置里每个角色需要指定一个 Model ID建议先在小规模对话里验证某个 Model ID 可用再写进团队配置。验证方式很简单用 curl 发一条最小请求curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: 你的ModelID, messages: [{role: user, content: 回复ok}], max_tokens: 16 }如果返回结构里有choices[0].message.content说明 Key、Base URL、Model ID 三件套都对上了。这一步看起来简单但后面 Agent Team 报错时很多问题根源就在这三者之一没对齐。2.3 环境变量与项目结构建议不要把 Key 硬编码进配置文件。建议用环境变量export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api项目结构建议按角色拆分配置文件方便后续调整agent-team/ ├── config/ │ ├── team.json # 团队角色与模型映射 │ └── subagents.json # Subagent 任务定义 ├── prompts/ │ ├── planner.md │ ├── coder.md │ ├── tester.md │ └── reviewer.md └── run.py # 调度入口这样拆的好处是调整某个角色的提示词不用动团队配置换模型只改team.json里的 Model IDSubagent 的任务边界在subagents.json里独立维护。3. 可复制配置Agent Team 模板与 Subagent 调度示例这一节给出可以直接复制运行的配置。所有配置里的 Base URL 统一为https://taotoken.net/apiKey 从环境变量读取Model ID 按你实际可用的填写。3.1 Agent Team 配置文件 team.json{ base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, team: [ { role: planner, model: 你的规划模型ModelID, system_prompt_file: prompts/planner.md, responsibility: 拆解任务、定义验收标准、决定调用哪些角色 }, { role: coder, model: 你的代码模型ModelID, system_prompt_file: prompts/coder.md, responsibility: 按规划实现代码改动 }, { role: tester, model: 你的测试模型ModelID, system_prompt_file: prompts/tester.md, responsibility: 补充测试用例、整理失败原因 }, { role: reviewer, model: 你的Review模型ModelID, system_prompt_file: prompts/reviewer.md, responsibility: 质疑方案、检查风险、给出修改建议 } ], shared_context: { task_board: tasks.json, max_rounds: 6, merge_strategy: planner_final } }关键字段说明shared_context.task_board指向共享任务板文件所有角色读写同一个任务列表max_rounds限制协作轮数防止无限讨论merge_strategy指定最终由 planner 汇总。3.2 Subagent 任务定义 subagents.json{ subagents: [ { name: code_search, model: 你的检索模型ModelID, task: 在指定目录中搜索与目标功能相关的文件和调用链只返回文件路径列表和每个文件的作用摘要不超过200字, output_format: summary_only }, { name: test_runner, model: 你的测试模型ModelID, task: 运行指定测试命令整理失败用例名称、失败断言、相关日志片段只返回结构化摘要, output_format: summary_only }, { name: doc_reader, model: 你的文档模型ModelID, task: 阅读指定模块的文档和注释总结关键设计决策和对外接口约定, output_format: summary_only } ] }output_format设为summary_only是 Subagent 的核心约束它不允许把原始日志或完整文件内容回传只能给摘要。这是保持主 Agent 上下文干净的关键。3.3 调度入口 run.py 核心逻辑import json import os import requests BASE_URL os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api) API_KEY os.environ[TAOTOKEN_API_KEY] def call_model(model_id, system_prompt, user_content): resp requests.post( f{BASE_URL}/v1/chat/completions, headers{ Content-Type: application/json, Authorization: fBearer {API_KEY} }, json{ model: model_id, messages: [ {role: system, content: system_prompt}, {role: user, content: user_content} ], temperature: 0.2 }, timeout120 ) resp.raise_for_status() return resp.json()[choices][0][message][content] def run_subagent(subagent_config, task_input): system_prompt f你是专项助手。任务{subagent_config[task]}。只返回摘要不要返回原始内容。 return call_model(subagent_config[model], system_prompt, task_input) def run_team(team_config, task): results {} for member in team_config[team]: with open(member[system_prompt_file], r, encodingutf-8) as f: system_prompt f.read() results[member[role]] call_model( member[model], system_prompt, task ) return results这段代码是最小可运行版本去掉了并发和重试方便你先跑通链路。跑通之后再按需加concurrent.futures做并行调用。3.4 提示词文件示例prompts/planner.md你是团队规划者。收到任务后你需要 1. 把任务拆成不超过5个子任务 2. 为每个子任务指定负责角色coder/tester/reviewer 3. 定义每个子任务的验收标准 4. 输出格式为 JSON字段subtasks[].id, subtasks[].owner, subtasks[].criteria 不要执行具体任务只做规划。prompts/reviewer.md你是代码审查者。你的职责是质疑不是附和。 收到方案或代码后你需要 1. 指出至少一个潜在风险 2. 指出至少一个可能被忽略的边界条件 3. 如果方案没有明显问题明确说未发现阻塞性问题 不要重写代码只给审查意见。4. 本地运行验证从单次调用到完整协作链路配置写好后按三步验证先验证单模型调用再验证 Subagent 调度最后验证 Agent Team 协作。4.1 第一步验证单模型调用python -c import os, requests r requests.post( https://taotoken.net/api/v1/chat/completions, headers{Authorization: Bearer os.environ[TAOTOKEN_API_KEY]}, json{model: 你的ModelID, messages: [{role:user,content:回复ok}], max_tokens: 16} ) print(r.status_code) print(r.json()[choices][0][message][content]) 预期输出状态码 200内容包含ok。如果这一步失败先不要往下走按第五节排查。4.2 第二步验证 Subagent 调度准备一个测试任务比如“在当前目录搜索所有包含 TODO 的文件返回文件列表和每个文件 TODO 数量摘要”。python -c import json from run import run_subagent with open(config/subagents.json) as f: subs json.load(f)[subagents] result run_subagent(subs[0], 在当前目录搜索所有包含 TODO 的文件) print(result) 预期输出一段摘要文本包含文件路径和数量不包含完整文件内容。如果返回了原始文件内容说明提示词里的summary_only约束没生效需要加强 system prompt。4.3 第三步验证 Agent Team 协作python -c import json from run import run_team with open(config/team.json) as f: team json.load(f) results run_team(team, 为登录功能增加异常登录检测并补充测试) for role, output in results.items(): print(, role, ) print(output[:300]) 预期输出四个角色各返回一段内容。planner 返回子任务拆解coder 返回实现方案tester 返回测试用例reviewer 返回审查意见。如果某个角色返回空或报错检查该角色的 Model ID 和提示词文件路径。4.4 验证协作质量跑通链路后重点看两件事第一planner 的输出是否被其他角色正确使用。如果 coder 完全忽略 planner 的子任务拆解说明角色之间的信息传递没接上需要在调度逻辑里把 planner 的输出作为后续角色的输入。第二reviewer 是否真的在质疑。如果 reviewer 每次都回“方案很好”说明提示词约束不够强需要明确要求它指出至少一个风险。5. 常见报错排查401、local proxy failed、reading choices、OAuth多 Agent 协作链路长报错定位比单 Agent 麻烦。这一节按真实报错整理排查路径。5.1 401 Unauthorized最常见的原因是 Key 没读到或格式不对。检查顺序echo $TAOTOKEN_API_KEY如果输出为空说明环境变量没导出。如果输出有值但请求仍 401检查请求头格式是否为Bearer sk-xxx注意Bearer和 Key 之间有一个空格。另一个容易忽略的点Key 是否被复制时带了换行或空格。用echo -n $TAOTOKEN_API_KEY | wc -c确认长度是否符合预期。5.2 local proxy failed这个报错通常出现在本地网络环境有额外转发配置时。排查方向确认TAOTOKEN_BASE_URL是否被错误地设成了带路径的地址。正确值应该是https://taotoken.net/api不要在后面加/v1或其他路径代码里会自动拼接。如果确认地址正确但仍报错检查本地是否有其他进程占用了请求端口或者环境变量里是否有冲突的代理设置。清理掉无关的代理环境变量后重试。5.3 reading choices 相关报错典型报错是KeyError: choices或list index out of range。这说明返回结构里没有choices字段通常是以下原因返回的是错误信息而不是正常响应。先打印完整响应体print(resp.status_code) print(resp.text)如果状态码是 4xx按对应错误处理。如果状态码是 200 但没有choices检查 Model ID 是否正确以及请求体里messages字段格式是否符合要求。5.4 OAuth 相关报错如果你在 Claude Code 或类似工具里配置时遇到 OAuth 报错通常是因为工具默认走了 OAuth 流程而你需要的是 API Key 模式。检查工具的配置文件确认认证方式设为 API KeyBase URL 设为https://taotoken.net/api并填入正确的 Key。以 Claude Code 为例配置文件里需要同时确认三件套Base URL、API Key、Model ID。缺任何一个都会导致认证失败。5.5 Agent Team 协作中的角色错乱如果发现 reviewer 在写代码、coder 在做规划说明角色提示词没有正确加载。检查team.json里system_prompt_file路径是否正确以及文件内容是否为空。另一个可能是模型本身对角色约束不敏感。这种情况下在 system prompt 开头加一句强约束比如“你只能做以下事情超出范围的内容一律不输出”。5.6 Subagent 返回内容过长如果 Subagent 返回了原始日志而不是摘要说明summary_only约束没生效。加强提示词你只能返回摘要。摘要不超过200字。禁止返回原始日志、完整文件内容、完整代码块。 如果任务需要返回列表列表项不超过10条。6. 从 Subagent 到 Agent Team按任务复杂度选择协作模式多 Agent 协作落地时最容易犯的错是一上来就搭完整 Agent Team。实际上大部分日常任务用 Subagent 就够了Agent Team 应该留给真正需要多视角校验的场景。我的建议是分三步走第一步先把 Subagent 跑通。选一个你日常重复做的任务比如“搜索某个功能的调用链”或“整理测试失败原因”把它拆成 Subagent 任务验证主 Agent 能拿到干净摘要。这一步的目标是建立“任务委派”的习惯。第二步在 Subagent 基础上加一个 reviewer 角色。让 reviewer 专门质疑其他角色的输出。这一步不需要完整团队配置只需要在调度逻辑里加一轮 review 调用。目标是验证多视角校验是否带来实际收益。第三步当任务确实需要多角色持续协作时再启用完整 Agent Team 配置。这时候你已经有了 Subagent 的任务边界管理经验和 reviewer 的质疑机制团队协作的混乱风险会低很多。如果你需要长期跑编码类 Agent 任务可以了解 Coding Plan 的接入方式如果只是先验证模型调用和协作链路模型对话页面可以直接测试接入文档里有完整的 Base URL、Key、Model ID 配置说明遇到配置问题可以先对照文档排查。整套流程跑下来核心就三件事Base URL 用https://taotoken.net/apiKey 从环境变量读Model ID 按角色分配。把这三件事固定住剩下的就是任务拆分和协作规则的设计这部分需要根据你自己的项目反复调整。