企业官网建设流程全解析

1. 项目缘起：当 AI Agent 从“玩具”变成“生产工具”

我先说一个很直接的感受：Coze 这个平台刚出来的时候，大多数人把它当成一个“聊天机器人组装工坊”，搭个问答机器人、做个文案助手，玩两天就扔了。但真正的分水岭出现在你开始认真思考“如何让一堆机器人协同干活”的时候。这次我要分享的项目，主题叫“基于 Coze API 的智能体体系”，副标题是“智能体来了（西南总部）如何构建 AI Agent 指挥官与 AI 调度官”。听起来有点唬人，其实拆开看就三件事：用 Coze API 把多个独立 Agent 串起来，用一个“指挥官”角色负责理解复杂任务，再用一个“调度官”角色把这些任务分发给合适的执行 Agent。

我为什么要做这件事？因为在实际业务里，单一 Agent 的能力天花板太明显了。你有文档问答机器人、有数据分析助手、有自动写周报的工具，但它们各自为政。用户提一个稍微复杂的请求，比如“帮我整理上个季度的销售数据、写一份分析报告、再生成一页给领导看的摘要”，你就得手动切换三四个系统。而“指挥官+调度官”这套体系，就是让用户只面对一个入口，剩下的事由 AI 自己去拆解、分发、汇总。

这套体系适合谁？适合已经有一定 Coze 使用经验、手里有几个现成 Agent、但觉得“单个机器人不够用”的人。也适合那些想在企业内部落地 AI 自动化流程、但不想从零训练模型、希望用低代码方式快速搭建中层调度逻辑的团队。说白了，这不是一篇教你写提示词的入门教程，而是一篇关于“Agent 体系架构怎么设计”的实操记录。

我在搭建这套体系时，选择的是 Coze API 作为底座。理由后面会详细讲，核心只有一句：Coze 把“模型能力、插件生态、知识库、工作流”都打包成 API 了，它天生就是做调度中枢的好材料。我在这套体系里亲手建了两个核心角色：Agent 指挥官和 AI 调度官，前者管“听懂”，后者管“分活”。下面我会把从设计思路、角色分工、API 接入、到踩坑实录的整个过程全部摊开来讲。

2. 体系设计思路：为什么一定要分“指挥官”和“调度官”两个角色

2.1 单体 Agent 的边界在哪里

动手之前，我先花了两天时间复盘了手头已有的几个 Agent 到底哪里不好用。结论是：它们单个都挺聪明，合在一起就变傻了。具体症状有三类：

第一，上下文割裂。文档问答 Agent 只记得你问文档的问题，数据分析 Agent 只认你发的表格路径。你把“先读一下这份报告，再算一下里面提到的增长率”丢给文档问答 Agent，它能给你读出文字，但算增长率就得你再切到另一个 Agent 重新发一遍内容，它俩毫无记忆共享。

第二，职责混乱。如果你把一个综合任务丢给某个专用 Agent，它会硬着头皮答非所问。比如让销售数据 Agent 帮忙起草邮件，它通常会给你生成一段“根据图表分析，我认为销售趋势良好”这种没头没尾的话，因为它的知识库里根本没有邮件模板和语境规则。

第三，缺乏任务优先级和依赖管理。一个任务可能需要先做 A 再做 B，A 的结果是 B 的输入。单体 Agent 不会自己安排这个顺序，它只会一次性把你的提示词扔给模型，结果就是模型靠猜来完成流程编排。

这些问题的根源是：我们只有执行层，没有决策层。所以必须引入一个“大脑”来统一接收需求、拆解步骤、安排执行顺序，这也就是指挥官和调度官存在的意义。

2.2 指挥官和调度官的分工逻辑

很多人会问：为什么不干脆做一个超级 Agent 把所有事都干了？我的答案是：可以，但没必要。超级 Agent 意味着你要在一个系统里维护所有领域的知识库、所有工具的描述、所有任务的判断逻辑，稍微一复杂，提示词就失控，模型也容易出现幻觉。更好的做法是把“决策”和“执行”分离。

在我的体系里，分工是这样的：

指挥官和调度官最大的区别在于：指挥官是“面向用户的”，调度官是“面向系统的”。指挥官不需要知道每个 Agent 内部用了什么模型、接了什么插件，它只需要判断“用户想要什么”。调度官也不需要理解用户的情感或深层需求，它只需要根据指挥官的输出，机械地把任务按依赖关系派发出去。

这个分离带来一个直接的好处：任何一个执行 Agent 升级换代，都不影响上层逻辑。比如我把原来的文档分析 Agent 从“常规模型”换成了“更强大的推理模型”，调度官那边只需要更新一下 Agent 描述和调用地址，指挥官根本不需要改动。这就是体系化架构最大的价值。

2.3 为什么选 Coze API 做底座

既然要做调度，就需要一个能统一调用多个 Agent 的接口层。我对比过几种方案：自研模型网关、用现成的 RPA 工具对接多个 SaaS、在 Coze 平台上直接用 Bot 编排 Bot。最后选定 Coze API，理由有三点。

第一，Coze API 天然支持 Bot 粒度的调用。每个 Coze Bot 就是一个独立的 Agent，它有自己的人格设定、知识库、工作流和插件。通过 API 发起会话时，你可以指定 bot_id，并且在同一会话中保持记忆。这对调度官来说太关键了——它可以把用户原始请求、指挥官的任务分解、执行 Agent 的回复全部串联在一个 session 里，不需要自己做复杂的记忆管理。

第二，插件生态降低了执行层的构建成本。以前我要让 Agent 查个天气、搜索个网页、读个数据库，都得自己写接口。Coze 插件市场里现成了一大堆，自己也能快速创建自定义插件，把公司的内部系统 API 包成插件喂给 Agent 就行。执行层越丰富，调度官的派活空间就越大。

第三，工作流功能可以承载调度逻辑本身。Coze 的工作流允许你写条件分支、循环、变量传递。调度官的核心逻辑，其实就是一个大工作流：接收指挥官输出的 JSON 任务列表，循环遍历每个任务，根据类型字段调用对应 Bot 的 API，然后把结果汇总。这部分用工作流做原型开发实在太快了，比写一套微服务快一个数量级。

当然 Coze API 也有它的限制，比如并发上限、响应超时时间等，这些我都会在后面的“踩坑实录”里专门讲。但作为一套智能体体系的中枢，它的性价比和灵活性目前没有更好的替代选择。

3. 核心角色解析：AI Agent 指挥官到底怎么“想”

3.1 指挥官的系统提示词设计思路

指挥官是整个体系的大脑，它的提示词决定了一个模糊请求能不能被拆解成清晰的任务清单。我在设计时遵循了一个核心原则：只输出结构化的任务分解结果，不输出具体执行内容。也就是说，指挥官不负责回答问题，它只负责告诉调度官“该干什么”。

初始版本的系统提示词大致框架如下：

你是一个 AI Agent 指挥官。你的职责是： 1. 仔细分析用户的请求，识别用户的真实意图。 2. 判断该请求需要哪些专业 Agent 协作完成。 3. 将请求分解为多个子任务，每个子任务必须包含： - task_id：子任务编号 - task_type：任务类型（document_analysis / data_query / text_generation / summary / search / ...） - input：该子任务需要的输入信息（可以是用户原始文本，也可以是上一任务的输出） - depends_on：依赖的前置任务编号列表 4. 以 JSON 数组格式输出你的任务分解结果，不要输出任何多余的解释文字。

关键点在于最后一条：“不要输出任何多余的解释文字”。为什么？因为指挥官的输出会被调度官直接解析，如果它夹杂着“好的，我来帮您分析一下……”这种废话，调度官解析 JSON 时就会出问题。我一开始没加这条约束，结果经常被模型的一两句客套话干扰，还得用正则去清洗，非常痛苦。

其次，要让指挥官具备“判断需要哪些资源”的能力，不能只靠它猜，得给它一份“可用 Agent 的目录”。我在提示词里加了一段“资源清单”：

当前可用的执行 Agent 清单如下： - 文档解析 Agent：负责读取 PDF、Word、Markdown 文件，提取文本内容。task_type 为 document_analysis。 - 数据分析 Agent：负责处理 CSV、Excel 数据，计算指标、生成图表。task_type 为 data_query。 - 文案生成 Agent：负责撰写邮件、报告、宣传文案等。task_type 为 text_generation。 - 摘要提取 Agent：负责对长文本进行总结、提炼要点。task_type 为 summary。 - 网页搜索 Agent：负责检索公开信息，返回相关链接和摘要。task_type 为 search。 当用户请求需要查阅外部资料、计算数据或生成文档时，请优先考虑以上 Agent。

这样指挥官才能合理地分配 task_type，而不是凭空编一个调度官根本不认识的任务类型。我在后续版本里还用 Coze 的知识库动态维护这份资源清单，这样新增 Agent 时不用改提示词，只要往知识库里加一条记录就行。这种做法的好处是：指挥官在每次对话开始时能自动加载最新清单，真正做到“即插即用”。

3.2 指挥官对模糊请求的应对策略

现实中的用户不会像写 API 文档那样提要求。他们常常说“你帮我看看这个数据有啥问题”，但完全不告诉你“数据”指的是哪个表、在哪个链接里。指挥官必须有主动澄清或合理推断的能力。

我在提示词里也做了约束：

如果用户请求中缺少必要的输入信息，你必须基于当前上下文做出最合理的推断，并在任务分解结果中加入 "assumptions" 字段，说明你做了哪些假设。例如： { "assumptions": ["用户提到的‘这个数据’默认指对话中最近一次上传的文件"] }

为什么要“推断”而不是“反问”？因为如果任何信息缺失都要反问，整个体系的效率就太低了。比如用户说“总结一下这份合同的风险点”，但没上传合同，指挥官如果反问“请上传合同”，用户就还得再操作一步；而如果指挥官假设“用户稍后会补充文件”，先把任务分解成“等用户上传文件→进行合同风险点提取→生成摘要报告”，调度官执行到第一步时发现没有文件，再触发追问，这样体验更流畅。

当然，推断结果必须明确记录在 assumptions 里，这样后续如果执行结果不对，人类可以追溯到底是哪个环节的假设出了问题。这套“可解释的任务分解”机制，也是我把指挥官和普通 Agent 区分开的关键。

3.3 从分解到执行的衔接协议

指挥官输出的 JSON 不能只给自己看，调度官和它之间必须有一个“协议”。我定义的衔接协议很简单，就是一个固定格式的 JSON：

{ "plan": [ { "task_id": 1, "task_type": "document_analysis", "input": "读取材料中的销售数据段落", "depends_on": [] }, { "task_id": 2, "task_type": "data_query", "input": "计算2024年Q3与Q2的环比增长率", "depends_on": [1] }, { "task_id": 3, "task_type": "text_generation", "input": "根据数据分析结果生成一页摘要报告", "depends_on": [2] } ] }

这个协议有三个好处：一是调度官能直接遍历 plan 数组，不用做语义理解；二是依赖关系通过 depends_on 明确表示，调度官可以判断并行与串行；三是每个子任务的 input 可以是上一任务的输出占位符，比如“根据任务 2 的输出结果”，调度官看到这种占位符就把对应任务的返回结果填充进去。

实际测试下来，指挥官在 90% 的情况下都能按这个格式输出。还有 10% 的情况它会漏字段，比如忘了写 depends_on，或者把 task_type 写成了完整句子。这些就需要调度官做一层“兜底清洗”，我后面会专门讲。

4. 核心角色解析：AI 调度官如何把“计划”变成“行动”

4.1 调度官的工作流设计

调度官不像指挥官那样需要大量语义理解能力，它更像一个“状态机 + 分发器”。我在 Coze 里用工作流实现调度逻辑，整个工作流分为六个节点：

• 节点一：接收输入。接收来自上游的原始用户请求和指挥官的 plan JSON。
• 节点二：清洗与校验。检查 plan 是否为合法 JSON，task_id 是否重复，depends_on 引用是否有效。如果格式错乱，尝试修复或要求指挥官重新生成。
• 节点三：拓扑排序。根据 depends_on 计算出任务的执行顺序。没有依赖的任务可以并行，有依赖的任务必须等前置任务完成。
• 节点四：循环执行任务。按排序后的顺序逐个调用对应执行 Agent 的 API。
• 节点五：结果收集。把每个任务的返回值存储到变量中，作为后续任务的输入。
• 节点六：最终汇总。将所有子任务的结果按用户需求组合成最终回复。

在 Coze 工作流里，“循环执行任务”这个节点是最难做的，因为 Coze 的工作流原生支持循环，但循环内的“动态调用不同 Bot”并不直接。我的做法是：先准备一个“Agent 路由表”，是一个 key-value 映射，把 task_type 映射到具体的 bot_id 和 API 参数模板。调度官拿到任务后，先查表，再根据模板构造 API 请求。

路由表我直接存成了一个 JSON，放在知识库里：

{ "document_analysis": { "bot_id": "737xxx", "endpoint": "document_agent", "params_template": {"file_url": "{input}"} }, "data_query": { "bot_id": "738xxx", "endpoint": "data_agent", "params_template": {"query": "{input}"} } }

这个设计让调度官完全不用关心每个 Agent 内部长什么样，它只负责按图索骥。

4.2 并行与依赖关系的处理策略

最初我以为调度官只需要按顺序一个一个调用就完事了，但很快发现效率太低了。比如用户要求“查询 A 产品的销量和 B 产品的销量”，这两个任务没有依赖关系，完全可以并行执行。但如果调度官串行跑，用户可能要等两倍的时间。

Coze API 本身是支持并发请求的，但在工作流里实现并行循环有点绕。我找到了一个折中方案：把没有依赖关系的任务打包成一个批次，用“多分支节点”并行触发。Coze 工作流里的“分支”可以根据条件同时执行多个路径，所以我先把 plan 按依赖层级分组，第一层任务放一个并行分支，第二层等第一层完成后再触发下一个并行分支。

实际操作时，节点设计大概是这样的：

• 接收解析后的任务组
• 用“分组器”把所有无依赖任务归为第一轮待执行组
• 创建 N 个并行的 API 调用子节点（N 等于第一轮任务数）
• 每个子节点完成后把结果写回变量数组
• 检查是否还有第二轮任务，如果有，把第一轮的输出作为第二轮输入，继续并行

这个逻辑用描述性文字来理解很容易，但在 Coze 工作流的图形界面里拖拽这些节点会非常繁琐，所以我最后改用了一个更省事的方法：把调度逻辑写成一段 Python 代码节点。Coze 支持自定义代码节点（服务端运行 Python），我直接在代码里用多线程调 Coze API，把整个调度流程打包成一个函数。这样我就不用跟工作流编辑器死磕并行逻辑了。

4.3 调度官如何做异常重试与信息传递

调度官一定会遇到执行 Agent 调用失败的情况，可能是网络超时，也可能是 Agent 返回了异常内容。我设置了三级重试机制：

第一级，HTTP 层面的重试。如果调用 Coze API 返回 5xx 或网络异常，等待 2 秒重试，最多重试 3 次。这是最简单也最有效的一级。

第二级，业务层面的重试。如果 API 返回成功，但执行 Agent 的回复为空、或者回复内容明显是错误提示（比如“我不明白你的意思”），调度官会重新组织 input，加一句“请严格根据输入内容执行，不要拒绝”，再调用一次。

第三级，降级策略。如果重试三次仍然失败，调度官不会把整个流程卡死，而是把失败标记写入结果，继续执行其他任务，最终汇总时告诉用户“有部分任务失败了，失败原因是……”。这比整体失败体验好得多。

信息传递方面，我最常踩的坑是长文本截断。数据分析 Agent 可能返回一个很长的表格数据，如果直接作为下一个任务的 input，Coze API 的字段长度限制可能会吃掉后半部分。我的解决方法是：在传递中间结果时，不直接传原始长文本，而是传给下一个 Agent 一个“摘要 + 数据获取链接”，也就是让执行 Agent 把结果存到临时存储（比如 Coze 的知识库或自己的对象存储），只返回一个引用标记。调度官看到引用标记，就知道要去哪个地址取完整数据。

这个“引用传参”的模式，是我这套体系能稳定跑大任务的关键。虽然会增加一点存储操作，但比把一个 10 万字的文档塞进对话上下文要安全得多。

5. 关键流程实战：从一条复杂指令到最终结果返回

5.1 一条指令触发的完整链路

我拿一个真实测试过的例子来走一遍完整链路。假设用户发来的请求是：

“帮我看看这份销售报告，重点分析西南区域上个季度的业绩，然后写一段总结，再根据总结生成三句老大在晨会能用的发言金句。”

这条请求如果丢给普通 Agent，大概率会得到一段含糊的文本。但在这套体系下，它会经历这样的旅程：

第一步，入口接入。用户消息先发送到 Coze API 的“总入口 Bot”，这个 Bot 其实就是指挥官。Coze 会把用户对话的 session_id 与后续所有子任务关联起来。

第二步，指挥官解析。指挥官在模型内部读完这段话，结合它知识库里的 Agent 资源清单，生成一个 JSON plan。我实测中它的输出大概是：

{ "plan": [ { "task_id": 1, "task_type": "document_analysis", "input": "读取销售报告文本，提取西南区域季度销售数据", "depends_on": [] }, { "task_id": 2, "task_type": "data_query", "input": "根据任务1提取的西南区域数据，计算本季度业绩完成率与环比增长率", "depends_on": [1] }, { "task_id": 3, "task_type": "summary", "input": "根据任务2的计算结果，撰写一段西南区域季度业绩总结，包含亮点与不足", "depends_on": [2] }, { "task_id": 4, "task_type": "text_generation", "input": "根据任务3的总结，生成三句适合晨会使用的励志总结金句", "depends_on": [3] } ] }

第三步，调度官接收 plan。它先清洗 JSON，检查字段完整性——这里没有缺失，于是开始拓扑排序。任务 1 最先执行，任务 2 依赖 1，任务 3 依赖 2，任务 4 依赖 3，是一条纯串行链路。调度官按顺序调用文档解析 Agent。

第四步，执行 Agent 干活。文档解析 Agent 拿到文件链接后，从 PDF 里抽取文本；数据分析 Agent 拿到文本后，定位“西南区域”相关行，计算结果；摘要 Agent 生成总结；文案 Agent 生成金句。

第五步，调度官汇总。把每一步的输出按顺序拼装，最终给用户返回：

报告显示，西南区域上季度销售额为 820 万元，环比增长 12%，完成目标的 96%。主要亮点是 B 产品线增长明显，不足是新客户转化率偏低。总结如下： [摘要内容] 晨会金句： 1. 西南区域稳步向前，核心产品持续发力。 2. 距离目标只差四个点，全力冲刺，目标必达。 3. 每一次复盘都是为了下一次更快的成长。

这条完整链路从发起到返回，平均耗时不固定，受到执行 Agent 数量影响，通常在 30 秒到 2 分钟之间。用户在总入口只发了一次消息，后面所有步骤都在后台悄悄完成。

5.2 关键 API 调用配置与参数细节

我给几个关键 API 调用的配置参数，这些是实测调出来比较稳的：

指挥官 Bot 的 API 调用参数：

• temperature：0.2 到 0.4。指挥官的任务是生成结构化 JSON，温度太高会导致字段名不稳定、格式偏差。我用 0.2，输出最稳定。
• max_tokens：800 到 1200。一个复杂 plan 的 JSON 文本通常在 500 token 左右，1200 足够，太大反而容易生成多余废话。
• response_format：如果 Coze API 支持强制 JSON（部分模型接口支持），尽量开启。我在 Coze 的 Bot 配置里把“输出格式”设置成 JSON 模式，显著降低了解析异常率。

调度官的代码节点参数：

• 并发线程数：我一开始设为 10，但 Coze API 某个版本对单账号并发请求有限制，后来发现同时跑 5 个请求左右最稳定。如果任务数超过 5，我会分批处理，每批最多 5 个并行。
• 超时时间：单次调用 Coze API 的超时设为 60 秒。一个简单的执行 Agent 通常在 10 到 20 秒内返回，但遇到复杂知识库检索时可能更久。60 秒是一个平衡值。

执行 Agent 的通用参数：

• 每个执行 Agent 都要在提示词里明确“你只负责 XXX 任务，不要输出无关内容”。我吃过亏，有个 Agent 跑着跑着就开始自我发挥，写起了小作文。

5.3 执行 Agent 的构建要点

调度官再怎么设计，最终交付结果的还是各个执行 Agent。我构建执行 Agent 时遵循了几个原则：

第一，每个 Agent 只做一件事，且提示词里必须写清输入输出的格式。比如数据分析 Agent 的输入一定是表格或结构化文本，输出一定是“指标名: 数值”的列表，或者一段可被直接引用的分析文字。如果输出太发散，后一个任务作为输入的时候就不稳定。

第二，尽量用知识库沉淀领域知识，而不是都塞进提示词。比如文案生成 Agent 里放了公司常用话术、晨会风格示例，摘要 Agent 里放了几篇高质量摘要范例。这样模型在生成时会参照知识库风格，而不是凭空自由发挥。

第三，每个执行 Agent 都要有“失败说明”能力。如果一个任务它做不了或输入数据不对，它必须明确输出“当前任务无法完成，原因是：……”，而不是硬编一个结果。调度官根据这个信号来决定是否降级或重新执行。

6. 实操过程与核心界面拆解：我是如何在 Coze 上一步步搭出来的

6.1 第一步：准备 Coze 环境与应用凭证

在开始搭建之前，先确认你的账号有 API 访问权限。Coze 目前提供了标准的 API 网关，你需要在控制台创建应用，拿到如下三类凭证：

• Personal Access Token：调用所有 API 的总令牌，用于身份验证。
• Bot ID：每个 Agent 对应一个 bot_id，创建 Bot 后在发布页能看到。
• Workspace ID：如果你的账号下有多个空间，需要指定 workspace_id，避免调用时找错 Bot。

创建应用后，建议把 Token 存到环境变量或密钥管理工具里，不要硬编码在代码节点中。我一开始图省事，把 Token 直接写在 Coze 代码节点里，后来发现任何人只要看到工作流导出文件就能窃取令牌，立刻改了。

6.2 第二步：创建指挥官和调度官 Bot

在 Coze 控制台创建一个 Bot，我命名为“Agent 指挥官”。它的配置包括：

• 人设与回复逻辑：填入上面提到的系统提示词。
• 模型选择：我用的是推理能力更强的模型版本，因为任务分解需要较强的语义理解。
• 知识库：挂载“可用 Agent 资源清单”的知识库。
• 插件：不需要插件，指挥官不需要访问外部工具。

之后再创建“AI 调度官”。调度官 Bot 的逻辑不是靠模型自由发挥，而是靠工作流驱动。我给它配置了一个自定义工作流，工作流里挂了一个 Python 代码节点，核心调度逻辑都在代码里。

这里有一个设计取舍：为什么不直接把调度官做成纯代码服务，而是放在 Coze 里？因为我想让调度过程也能被非开发人员可视化审查。Coze 工作流界面能展示每一步调用了哪个 Agent、传了什么参数，业务人员可以直观看到整个链路。虽然并行逻辑用代码节点实现，但整体框架在工作流图上依然清晰。

6.3 第三步：创建执行 Agent 群

根据业务需要，我创建了文档解析、数据分析、文案生成、摘要提取、网页搜索五个执行 Agent。每个 Agent 都需要在发布时生成 bot_id，然后我手工把这些 bot_id 写进调度官引用的 JSON 路由表里。

创建执行 Agent 的一个关键点：设置好“人设”与“回复逻辑”中的输入输出规范。以数据分析 Agent 为例，我在它的提示词里写了：

你是一个数据分析助手。用户会给你一段结构化文本或文本描述。你的任务是： 1. 提取文本中所有数值、日期、地区等信息。 2. 按用户要求的计算方式给出结果。 3. 输出格式为 Markdown 表格，包含指标名称、数值、说明。 不要输出与数据无关的内容。

这段提示词决定了执行 Agent 的输出天然适合被下一个任务引用。如果输出格式是自由文本，调度官后续处理时还得再做一轮解析，增加了出错概率。

6.4 第四步：打通入口与总调度逻辑

所有 Agent 创建完后，我做了两件事将它们串联：

第一，把“指挥官”设置成平台的“总入口 Bot”。用户在客户端（比如一个企业微信机器人或网页应用）里发送的所有消息，都先调用指挥官 Bot 的 API，拿到 JSON plan。

第二，写了一个“总调度器”服务。它可以是一个 Coze 工作流，也可以是一段独立 Python 脚本。我先用 Coze 工作流做原型，跑通后再把调度器部署为独立服务，方便调试。

总调度器的核心伪代码如下：

def dispatch(user_request, session_id): plan = commander_agent.chat(user_request) tasks = json.loads(clean_json(plan)) ordered_tasks = topo_sort(tasks) results = {} for task in ordered_tasks: if task['depends_on']: # 将依赖任务的结果注入输入 task['input'] = fill_input(task['input'], results) results[task['task_id']] = call_execution_agent(task, session_id) final_answer = assemble_results(results) return final_answer

写完这个伪代码后，再逐个实现 commander_agent.chat 和 call_execution_agent 即可。Coze API 的调用方式我直接用了官方 SDK，传入 bot_id、query、session_id 等参数就行。

6.5 现场测试实录：从调试到稳定的过程

第一次联调时，场面非常混乱。最大的问题是指挥官不按 JSON 格式输出，它经常在 JSON 前后加“好的，我已经为您解析任务如下：”这样的前言。我不得不加了一层正则清洗，但仍然不稳定。最终解决方式是：在系统提示词里增加了“禁止输出任何前言或后语，只输出 JSON”，并且把这段提示词放在最后一句。效果立竿见影，JSON 解析成功率从 70% 提升到 95% 以上。

第二次联调遇到的坑是依赖参数传递错误。任务 2 需要任务 1 的输出，但调度官传给任务 2 的却是用户原始输入。检查发现是 fill_input 函数里的变量名写错了，把results['task_1']写成了results[1]。这个错误花了我半天才定位，因为错误信息不明显，只是任务 2 回复“我没有找到数据”。

第三次联调时，并发任务出现了资源竞争。两个并行任务同时调用一个执行 Agent，Coze API 限流导致其中一个返回 429。后来我在调度代码里加了一个简单的信号量（同时最多允许 3 个请求打向同一个 bot_id），这个问题就消失了。

经过这三轮打磨，完整链路的成功率从最初的 40% 提升到了稳定期的 90% 以上。

7. 常见问题与排查技巧实录

这套体系搭起来后，日常运行中会遇到不少问题和异常。我把最有代表性的几个列成速查表，附带解决思路。

除了这些常见问题，还有几个我在真实环境中踩到的“隐性坑”值得单独说一说。

第一个坑是session_id 的复用问题。Coze API 支持在同一个 session 里继续对话，但不同 Bot 之间是否共享会话记忆，取决于你的 API 调用方式。我一开始默认所有子任务共用同一个 session_id，结果发现执行 Agent 之间会互相干扰——文档解析 Agent 的上下文里混进了数据分析 Agent 的中间输出，导致它解析时引用错误。后来我的做法是：每个子任务使用独立的 session_id，但调度官自己在服务端维护一个“全局上下文”，只在需要时把必要字段传给子任务。这样既保留了跨 Agent 的信息流，又隔离了无关记忆。

第二个坑是输入文本中的特殊字符。如果用户提交的文档里含有大量换行、引号、反斜杠，Coze API 在传输时可能会转义出问题。我在调度器里对输入做了统一转码，把换行替换为占位符，把引号转义，等进入 Agent 后再还原。这个处理避免了大量莫名其妙的格式错乱。

第三个坑是执行 Agent 的“过度思考”。有些执行 Agent 收到一个简单数据任务，却在回答里写了一大段方法论解释，甚至“通过以上分析，我们可以得出……”。这对汇总输出很不友好。我后来在每个执行 Agent 的提示词里都加了一句“如果你认为任务简单，也请直接给出结果，不要解释你的分析过程”。加了这句话之后，输出干净了一大半。

8. 个人实操心得与下一步扩展思考

整套体系跑通之后，我最大的感受是：AI Agent 体系的复杂度不在模型，而在“角色边界”的划分。指挥官和调度官如果职责混在一起，系统很快就会乱成一锅粥；一旦明确分工，每个角色的提示词、工作流和错误处理都能独立优化，整个体系的可维护性就大大提升。

我另外还想分享一个细节技巧：把调度逻辑做成“可观测”的。我一开始只关注最终回复，出了问题很难定位是哪个环节挂了。后来我在每个调度环节都往日志里写了一条记录，比如“task 1 调用 document_agent 成功，耗时 12 秒，返回前 100 字为……”这样出现问题后翻日志就能快速定位到具体 Agent。对任何多 Agent 协作系统，日志的精细程度决定了你的排障效率。

后续我计划在这个基础上再增加一个“质量审计 Agent”。它不参与执行，只在最终回复返回前，检查一遍汇总内容是否覆盖了用户原始请求的所有要点。比如用户要求“总结 + 金句”，如果调度官只返回了总结却漏了金句，审计 Agent 就会发现并触发一次补做。这个机制相当于给体系加了一层“质检员”，能让最终交付的成功率进一步提升。

如果你正在尝试构建类似的多 Agent 体系，我建议从最小的“一个指挥官 + 一个调度官 + 两三个执行 Agent”开始，先把链路跑通，再逐步扩大 Agent 群。这套体系的魅力在于：每增加一个执行 Agent，并不是简单多一个功能，而是整个调度网络的复杂度会随之上升，但回报也非常直接——你的 AI 体系能处理的任务范围会呈指数级扩展。现在我的这个“西南总部”项目已经稳定运行，日常办公中很多跨文档、跨数据的复杂请求，都交给了这套智能体体系来处理，省下的时间和精力非常可观。