1. 多 Agent 协作真正难的地方不是“多”而是“乱”单 Agent 跑通之后很多人第一反应是“再拆几个 Agent 就生产级了”。我一开始也这么想直到把市场、财务、法务三个角色塞进同一条链路才发现问题根本不在模型能力而在协作协议Supervisor 反复调用同一个 Sub-Agent、每个 Agent 都复制一份完整对话导致 Token 树状膨胀、两个 Agent 基于不同 State Version 工作、Blackboard 里的临时提案被下游当成正式事实、晚到的结果覆盖了最终结论。这一篇要解决的就是这些。核心思路是用 TaoToken 统一 Key 和 API 通道让 Supervisor 和所有 Sub-Agent 走同一个模型调用入口然后把控制权、上下文边界、共享状态、预算门禁这四件事用代码固定下来。适合已经写完单 Agent、准备上多 Agent 协作的开发者也适合正在被“Agent 之间自由聊天同步世界”坑到的人。读完你能拿到一份可复制的config.toml与settings.json骨架、Supervisor 路由与 Blackboard 共享状态读写示例、多 Agent 协作链路的验证动作以及一份排错清单。2. 前置用 TaoToken 统一多 Agent 的模型调用入口多 Agent 系统里最容易被忽略的工程细节是每个 Agent 都在自己拼 API Key、自己处理重试、自己算成本。一旦拆到 5 个 Sub-AgentKey 管理、限流、成本归因全乱套。我的做法是把模型调用收敛到一层所有 Agent 通过 TaoToken 的 OpenAI 兼容接口访问模型Key 只在网关侧配置一次Sub-Agent 拿到的只是“角色 能力”不接触凭证。TaoToken 在这里承担的是统一 API 通道的角色Supervisor、Research、Finance、Legal 这些角色共用同一个 base_url 和 Key但通过不同的 model profile 和 tool 权限做隔离。这样成本归因、并发控制、模型切换都在一处完成不用在每个 Agent 里重复实现。你需要先准备两样东西一个可用的 API Key在控制台的 API Keys 页面创建https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite确认接入方式文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI 基地址统一用https://taotoken.net/api不要带任何查询参数。下面所有配置都基于这个地址。注意Key 只放在服务端配置或环境变量里不要写进前端、不要提交到仓库。Sub-Agent 的 Task Envelope 里只传modelProfile名称不传 Key。3. 可复制配置config.toml 与 settings.json 骨架先给一份能直接落地的配置。config.toml负责运行时参数settings.json负责 Agent Catalog 和策略。3.1 config.toml[provider] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY timeout_seconds 60 max_retries 2 [provider.concurrency] global_max 32 per_model_max 8 per_run_max 6 per_role_max 2 [supervisor] max_delegation_depth 1 max_tasks_per_run 12 max_children_per_task 4 default_join_policy QUORUM quorum 2 plan_version v3 [budget] token_limit 800000 model_call_limit 400 tool_call_limit 600 cost_limit 12.00 deadline_seconds 900 [budget.reserve_order] reserved_roles [security_check, reviewer, merge] [blackboard] schema_version bb-v2 max_state_bytes 2097152 artifact_retention_days 30 [freshness] maximum_version_lag 2 maximum_age_seconds 300 invalidating_paths [/plan, /goal, /budget_limit] invalidating_artifact_types [market_snapshot, legal_opinion]这里几个参数值得单独说。max_delegation_depth 1意味着只允许 Supervisor 委派给 Sub-AgentSub-Agent 不能再往下委派这是防止循环委派最省事的做法。reserve_order保证安全检查和 Reviewer 的预算先被预留否则前面的研究 Agent 花完预算最后没法验证。3.2 settings.json{ agents: [ { role: supervisor, description: 目标解析、任务分配、预算控制、Join 与冲突升级, capabilities: [plan, delegate, merge, escalate], allowedToolCategories: [read_only, internal], modelProfile: reasoning-large, maximumRisk: HIGH, promptVersion: sup-v3 }, { role: research, description: 市场与竞品信息检索产出结构化 Claim, capabilities: [search, summarize], outputArtifactTypes: [market_snapshot, claim_set], allowedToolCategories: [web_read, internal_search], modelProfile: reasoning-medium, maximumRisk: LOW, promptVersion: res-v2 }, { role: finance, description: 财务测算与收益评估, capabilities: [calculate, model], outputArtifactTypes: [finance_model, claim_set], allowedToolCategories: [calc, internal_search], modelProfile: reasoning-medium, maximumRisk: MEDIUM, promptVersion: fin-v2 }, { role: legal, description: 合规风险识别与条款审查, capabilities: [review, flag_risk], outputArtifactTypes: [legal_opinion, risk_item], allowedToolCategories: [internal_search], modelProfile: reasoning-large, maximumRisk: HIGH, promptVersion: leg-v2 } ], joinPolicy: { default: QUORUM, quorum: 2, mandatoryRoles: [legal], deadlineFallback: DEADLINE }, handoff: { maximumTransfers: 2, userVisible: true, userConfirmationRequired: true } }mandatoryRoles是关键即使 Quorum 已经满足法务这种高风险角色也不能被跳过。maximumTransfers限制 Handoff 次数避免两个 Agent 来回踢皮球。4. Supervisor 路由与 Blackboard 共享状态读写配置只是骨架真正决定系统是否可控的是 Supervisor 怎么派活、Blackboard 怎么写。4.1 Task Envelope 不可变Supervisor 派给 Sub-Agent 的不是完整对话而是一个不可变的 Task Envelopepublic record AgentTaskEnvelope( String taskId, String runId, String parentTaskId, AgentRole assignedRole, String objective, ListArtifactRef inputs, SetString constraints, SetString allowedCapabilities, String outputSchemaVersion, long sharedStateVersion, BudgetAllocation budget, CommitToken commitToken, Instant deadline ) {}Sub-Agent 只拿到当前目标、必要约束、相关 Artifact、允许的 Tool 和输出契约。完整会话里的无关历史、旧事实、其他领域敏感信息全部不进 Envelope。这一步直接决定了 Token 成本是线性还是树状。4.2 Supervisor 路由伪代码def route(goal: MultiAgentGoal, catalog: AgentCatalog) - MultiAgentPlan: candidates [] for task_def in decompose(goal): for agent in catalog.by_capability(task_def.required_capability): score ( 0.4 * relevance(agent, task_def) 0.3 * expected_value(agent, task_def) - 0.2 * estimated_cost(agent, task_def) - 0.1 * estimated_latency(agent, task_def) ) candidates.append((task_def, agent, score)) selected select_with_budget(candidates, goal.budget) return MultiAgentPlan( planIdnew_id(), version1, tasksselected, joinPolicygoal.join_policy, quorumgoal.quorum, budgetgoal.budget, planHashhash_plan(selected), )注意select_with_budget会先扣掉安全检查和 Reviewer 的预留预算剩下的才分给可选研究 Agent。4.3 Blackboard 分区与写入权限Blackboard 不是一个大 JSON而是按 Path 授权的工作区/goal # 只读Supervisor 写 /plan # 只读Supervisor 写 /tasks # Agent 只能更新自己 Task 状态 /artifacts # 只追加不可原地覆盖 /claims # 只追加 /conflicts # 只追加 /open_questions # 可追加、可关闭 /proposals # Agent 提交Supervisor/Human 决定 /decisions # 只读Commit 后写 /budget # 只读Budget Service 写Sub-Agent 能做的只有发布 Artifact、提交 Proposal、更新自己 Task 状态、报告风险。它不能直接改/goal、/final_decision、/approvals、/budget_limit。4.4 乐观锁写入共享状态更新必须带版本号并发冲突不能静默覆盖update multi_agent_shared_state set state_json :state, version version 1 where run_id :runId and version :expectedVersion;如果影响行数为 0说明版本已经变了当前写入必须走 Proposal 重新评估而不是重试覆盖。4.5 Proposal / Commitpublic record StateChangeProposal( String proposalId, String runId, String taskId, AgentRole proposer, long baseVersion, ListJsonPatchOperation changes, ListArtifactRef evidence, String reason ) {}Supervisor、规则引擎或 Human 决定是否 Commit。Commit 前要校验 Commit Token、输入 Artifact 版本和 Shared State 新鲜度。5. 验证请求与成功结果配置和代码就位后用一条最小链路验证Supervisor 派两个 Sub-Agent 并行Blackboard 收到两个 ArtifactMerge 产出结论。5.1 发起一次多 Agent Runcurl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: reasoning-large, messages: [ {role: system, content: 你是 Supervisor负责目标解析与任务分配。}, {role: user, content: 评估方案A是否值得推进需要市场、财务、法务三方输入。} ], metadata: { run_id: run_20250101_001, role: supervisor, plan_version: v3 } }5.2 期望的 Trace 结构multi_agent.run ├─ router ├─ supervisor.plan ├─ budget.reserve ├─ task.research ├─ task.finance ├─ task.legal ├─ join ├─ merge ├─ review └─ human5.3 成功判定的几个硬指标指标期望值说明stale_result_commit_total0晚到结果被拒绝commit_rejected_total{reason}可解释拒绝原因可归因context_duplication_rate 0.25重复上下文占比task_success_rate≥ 0.90必需 Task 成功率unresolved_blocking_conflicts0阻塞冲突清零如果context_duplication_rate超过 0.25基本可以断定 Context Builder 把完整会话塞给了每个 Sub-Agent需要回到 Task Envelope 检查。6. 本篇常见错排查6.1 Supervisor 重复调用同一 Agent现象Trace 里同一个 role 出现多次Task 内容高度相似。排查检查planHash是否在重试时被重新生成。正确做法是 Plan 一旦生成就绑定planHash重试复用原 Plan只重跑失败 Task。6.2 Sub-Agent 复制完整上下文现象multi_agent_context_duplication_tokens飙升。排查确认 Sub-Agent 的输入来自ContextManifest而不是原始消息列表。Context Builder 只应包含当前目标、必要约束、相关 Artifact、允许 Tool 和输出预留。6.3 共享状态被覆盖现象两个并行 Task 提交后只有一个 Artifact 生效。排查检查是否用了乐观锁。version不匹配时必须走 Proposal不能直接 update。6.4 晚到结果污染最终结论现象Task 已被取消但结果仍然写入了/artifacts。排查提交时校验 Commit Token 和 Task 状态。状态为SUPERSEDED或CANCELLED的 Task提交直接返回TASK_NOT_ACTIVE。6.5 预算被前面 Agent 花完现象Reviewer 无法执行最终结论没有验证。排查确认reserve_order生效安全检查和 Reviewer 的预算在 Task 启动前就被原子预留。6.6 多数投票形成集体幻觉现象三个 Agent 结论一致但都基于同一份数据、同一个模型。排查记录model family、evidence source、prompt lineage。三票一致不等于三个独立证据真正的冗余验证要求不同证据、不同模型或规则、独立 Context。6.7 Handoff 来回跳转现象两个 Agent 互相转交用户看到身份反复切换。排查检查HandoffPolicy.maximumTransfers和allowedTargets。控制权回收必须在 Policy 中定义不能自由跳转。6.8 版本 Gap 导致状态错乱现象本地投影版本 15收到事件版本 18。排查不要直接应用事件读取 Version 18 的 Snapshot 替换本地投影。消费者必须检测版本 Gap。7. 下一步把 Key 和通道固定下来再谈协作多 Agent 协作的复杂度不在模型而在协议。Supervisor 管目标和预算Sub-Agent 处理专业任务Artifact 承载可复用事实Shared State 记录正式状态Blackboard 管理提案与冲突Commit Gate 阻止旧结果Reviewer 和 Human 控制最终风险。而这一切的前提是模型调用入口先统一。如果你还在每个 Agent 里各配一份 Key、各写一套重试协作层再漂亮也会被凭证和成本问题拖垮。建议先把 TaoToken 的 Key 和 API 通道固定下来创建 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite需要长期跑编码类 Agent 或 Supervisor 编排可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite想先验证模型在多 Agent 场景下的表现直接进模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite下一篇会继续实现代码与浏览器沙箱、安全执行与风险控制。在那之前先把这一篇的config.toml和settings.json跑通确认 Trace 里stale_result_commit_total为 0、context_duplication_rate低于 0.25再往上叠功能。