Deep Agents 工作流实战：多 Agent 协作模式下的配置文件骨架与验证

1. 从单 Agent 到多 Agent为什么你的工作流需要一份配置文件骨架如果你已经在本地跑通过单个 Agent大概率会遇到一个瓶颈一个 Agent 既要做需求拆解又要写代码还要自己检查结果最后往往在某个环节开始胡言乱语。这不是模型不行而是角色没有拆开。Deep Agents 工作流的核心思路就是把一个复杂任务拆给多个职责单一的 Agent让它们按约定的协作模式串起来或并行跑。多 Agent 协作听起来很酷但真正落地时第一个卡住人的不是模型能力而是配置。角色怎么定义、谁调用谁、上下文怎么传递、工具权限怎么隔离这些如果全靠代码硬编码改一次就要动一次源码。所以更工程化的做法是把协作关系抽到配置文件里用config.toml描述 Agent 角色与协作拓扑用settings.json描述运行时参数与模型绑定。这样你调整协作链路时只改配置不动逻辑。这篇内容面向的是需要在本地搭建多 Agent 协作链路的开发者。我会给出可直接复制的config.toml与settings.json骨架说明各 Agent 角色与协作模式的字段映射关系然后带你启动一次真实请求验证协作链路是否真的生效。整套流程围绕 Deep Agents 多 Agent 协作工作流展开适合已经会调用大模型 API、想进一步做 Agent 编排的人。需要提前说明的是多 Agent 协作不是 Agent 数量越多越好。两个职责清晰的 Agent往往比五个互相甩锅的 Agent 更稳定。配置文件的价值恰恰是让你能清楚地看到谁负责什么而不是把复杂度藏进代码里。2. TaoToken 前置准备把模型调用层先跑通在写多 Agent 配置之前得先保证模型调用这一层是通的。多 Agent 协作会放大请求量一个任务可能触发十几次模型调用所以调用层要稳定、要能统一管理 Key 和模型 ID。我这边用的是 TaoToken 作为模型接入层它提供 OpenAI 兼容的接口配置进settings.json里比较省事。先拿到 API Key。访问 API Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdeepagents_config登录后创建一个新 Key复制出来。注意 Key 只在创建时完整显示一次丢了就得重建。拿到之后先别急着写进多 Agent 配置先用一条最简单的请求验证它能不能通。TaoToken 的 API 基地址是https://taotoken.net/api这个地址不加任何查询参数直接作为base_url使用。模型 ID 方面你可以先在模型对话页面确认当前可用的模型名称https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdeepagents_config在页面上选一个你打算用作主力推理的模型把它的 ID 记下来比如常见的claude-sonnet-4-5或gpt-4o这类命名。多 Agent 场景下我建议至少准备两个模型 ID一个能力强、用于规划类 Agent一个速度快、用于执行类 Agent。这样在settings.json里可以按角色分配控制成本和延迟。用 curl 做一次连通性验证把YOUR_API_KEY换成你刚创建的 Keycurl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d { model: claude-sonnet-4-5, messages: [ {role: user, content: 只回复两个字通了} ] }如果返回的 JSON 里choices[0].message.content是通了说明调用层没问题。这一步很关键因为后面多 Agent 报错时你要能快速判断是协作配置的问题还是底层调用就没通。很多人排查半天协作链路最后发现是 Key 写错了或者模型 ID 不存在白白浪费时间。如果你打算长期跑编码类或 Agent 类任务可以顺带了解一下 Coding Plan它在高频调用场景下更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdeepagents_config前置准备做完接下来进入正题写配置文件。3. 可复制配置config.toml 与 settings.json 骨架多 Agent 协作的配置分两层。config.toml描述有哪些 Agent、它们怎么协作settings.json描述运行时怎么调用模型、超时多少、重试几次。分开的好处是协作拓扑和运行参数互不干扰调一个不会影响另一个。先看config.toml。下面这份骨架定义了三个 Agent一个 planner 负责拆解任务一个 executor 负责执行一个 reviewer 负责校验。协作模式用mode字段控制支持sequential顺序、parallel并行、supervisor主管调度三种。# config.toml [workflow] name deep-agents-demo mode supervisor # sequential | parallel | supervisor max_turns 12 # 整个协作链路最多交互轮数 timeout_seconds 300 # 单次协作总超时 [workflow.supervisor] agent planner # 主管 Agent负责调度其他 Agent allow_reassign true # 允许主管把任务重新分配给别的 Agent [[agents]] id planner role task-planner description 把用户需求拆解为可执行的子任务列表 model_ref strong # 引用 settings.json 里的模型别名 tools [read_file, list_dir] can_delegate [executor, reviewer] [[agents]] id executor role code-executor description 根据子任务执行具体操作产出结果 model_ref fast tools [read_file, write_file, run_shell] can_delegate [] [[agents]] id reviewer role result-reviewer description 校验 executor 的产出是否符合子任务要求 model_ref strong tools [read_file] can_delegate [executor] # 发现问题可打回给 executor 重做 [collaboration] share_context true # 是否共享上下文 context_window 8000 # 共享上下文的最大 token 数 pass_full_history false # 只传摘要避免上下文爆炸几个字段值得展开说。mode supervisor表示由 planner 作为主管来调度它决定下一步交给谁。如果你改成sequential就会按[[agents]]的定义顺序依次执行适合流程固定的场景。can_delegate是权限控制planner 能派活给 executor 和 reviewer但 executor 不能反过来派活避免无限循环。model_ref不直接写模型 ID而是引用别名这样换模型时只改一处。再看settings.json它负责运行时参数和模型绑定{ runtime: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, max_retries: 3, retry_backoff_ms: 800, request_timeout_ms: 60000 }, models: { strong: { model_id: claude-sonnet-4-5, temperature: 0.2, max_tokens: 4096 }, fast: { model_id: gpt-4o-mini, temperature: 0.1, max_tokens: 2048 } }, logging: { level: info, log_agent_turns: true, log_file: ./logs/deep-agents.log } }注意api_key_env这一项它指向环境变量名而不是把 Key 明文写进 JSON。这是基本的安全习惯配置文件可能会进版本库Key 不能跟着进去。启动前设置环境变量export TAOTOKEN_API_KEY你创建的Keylog_agent_turns true在多 Agent 调试时非常有用它会把每个 Agent 的输入输出按轮次记下来协作链路哪里断了翻日志一目了然。max_retries和retry_backoff_ms配合能扛住偶发的网络抖动多 Agent 场景下请求密集重试机制能省不少心。两份配置放同一目录比如./deep-agents/。目录结构建议这样deep-agents/ ├── config.toml ├── settings.json └── logs/logs/目录要提前建好否则写日志时会报路径不存在。4. 启动与验证确认协作链路真的生效配置写完接下来是验证。多 Agent 最容易出的问题是看起来跑了其实只有一个 Agent 在干活所以验证不能只看有没有返回结果要看协作链路有没有真的被触发。启动时指定配置目录deep-agents run \ --config ./deep-agents/config.toml \ --settings ./deep-agents/settings.json \ --task 读取当前目录下的 README.md总结项目用途并检查总结是否遗漏关键信息这条任务故意设计成需要协作planner 拆解成读取文件总结校验三个子任务executor 执行读取和总结reviewer 校验总结质量。如果协作链路正常日志里应该能看到三个 Agent 的轮次记录。观察日志文件tail -f ./logs/deep-agents.log正常生效的日志大致长这样[planner] turn1 actiondelegate targetexecutor taskread README.md [executor] turn2 actionrun_shell cmdcat README.md statusok [executor] turn3 actiondelegate targetreviewer taskverify summary [reviewer] turn4 actionread_file path./README.md statusok [reviewer] turn5 actionapprove resultsummary complete [planner] turn6 actionfinish statusdone看到delegate和approve这类动作说明协作模式在起作用。如果日志里从头到尾只有[planner]那说明主管没有把任务派出去多半是can_delegate配错了或者mode没设成supervisor。再验证一下并行模式。把config.toml里的mode改成parallel重启后跑一个可以并行的任务deep-agents run \ --config ./deep-agents/config.toml \ --settings ./deep-agents/settings.json \ --task 分别统计 src 目录下 .py 和 .js 文件的数量并行模式下executor 和 reviewer 会同时启动日志里两个 Agent 的 turn 编号会交错出现。如果它们还是严格顺序执行检查一下[collaboration]里的share_context是否被误设成了false某些实现下并行 Agent 需要共享上下文才能同时调度。验证成功的标准很简单日志里出现了多个 Agent 的 id并且有明确的delegate、approve、reject这类协作动作。只要这几点满足说明你的多 Agent 协作链路已经跑通了。5. 常见报错排查401、local proxy failed 与 reading choices多 Agent 配置跑不起来报错往往集中在几个地方。下面按真实遇到的频率排一下对照着查能省很多时间。401 Unauthorized。这是最常见的一个基本是 Key 的问题。先确认环境变量有没有生效echo $TAOTOKEN_API_KEY如果输出为空说明export没在当前 shell 生效或者你换了终端窗口。重新 export 一次或者写进~/.bashrc。如果 Key 有值但还是 401检查settings.json里的api_key_env是否和实际环境变量名一致大小写敏感。还有一种情况是 Key 被删了或者过期了去 API Keys 页面重新建一个。local proxy failed / connection refused。这个报错通常和base_url有关。确认settings.json里写的是https://taotoken.net/api不要多加斜杠也不要写成/v1之类的路径。多 Agent 框架有些会在base_url后面自动拼/chat/completions你手动加了路径就会变成双份导致 404 或连接失败。另外确认本机网络能正常访问该地址用前面的 curl 命令再测一次。Error reading choices / choices is empty。这个报错说明请求发出去了但返回体里没有choices字段。常见原因有三个一是模型 ID 写错了服务端返回的是错误信息而不是正常响应二是max_tokens设得太小模型还没输出就被截断三是请求体格式不对比如messages数组为空。排查时先把log_agent_turns打开看实际发出的请求体长什么样。如果模型 ID 不确定去模型对话页面复制准确的 ID。OAuth / token expired。如果你用的是需要 OAuth 的接入方式token 过期会报这个。多 Agent 长时间运行时尤其容易碰到因为一个任务可能跑十几分钟。解决办法是在settings.json里把max_retries设成 3 以上配合retry_backoff_ms让框架在 token 刷新后自动重试。如果频繁过期考虑换成 API Key 方式稳定性更好。Agent 之间互相甩锅、无限循环。这不是报错但比报错更烦。表现是 planner 把任务派给 executorexecutor 又派回 planner来回好几轮不结束。根因通常是can_delegate配得太宽松或者max_turns设得太大。把can_delegate收紧只允许主管派活执行类 Agent 不允许反向委派。同时把max_turns设成一个合理值比如 12超过就强制结束并返回当前结果。上下文爆炸导致响应变慢或截断。多 Agent 共享上下文时历史消息会越积越多。如果pass_full_history设成了true几轮之后 token 就爆了。改成false只传摘要同时把context_window控制在 8000 以内。实测下来摘要模式对协作质量影响不大但速度和成本改善明显。排查时记住一个顺序先确认底层调用通不通curl 测再看配置字段对不对对照本文骨架最后看日志里协作动作有没有发生。按这个顺序走大部分问题十分钟内能定位。6. 把协作链路用起来从验证到日常配置跑通只是起点。真正让多 Agent 协作产生价值的是把它接到你日常的开发流程里。比如代码审查场景planner 拆解审查维度executor 逐文件检查reviewer 汇总问题并按严重程度排序最后输出一份可操作的清单。又比如文档生成planner 定大纲executor 填内容reviewer 查一致性三个角色各司其职。如果你打算把这条链路长期跑起来建议把配置纳入版本管理但 Key 走环境变量。每次调整协作模式时先在小任务上验证确认日志里的协作动作符合预期再放到大任务上。多 Agent 的调试成本比单 Agent 高但一旦配置稳定它能处理的任务复杂度也是单 Agent 比不了的。需要继续深入的话接入文档里有更完整的字段说明和进阶用法https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdeepagents_config模型对话页面可以随时验证某个模型 ID 是否可用改配置前先在那里确认一下能避免不少低级错误https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdeepagents_config最后留一个我踩过的坑多 Agent 配置里最容易忽略的是logs/目录的写权限。容器或 CI 环境里工作目录可能是只读的日志写不进去会导致启动直接失败但报错信息往往指向别处。启动前先确认日志目录可写能省一轮排查。