跳到正文
Ankole

Workflow:并行子 Agent

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/workflows/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

借助 Workflow,主对话 Agent 可以编写并运行一段确定、有界的编排程序,将一批彼此独立的子任务分发给多个子 Agent 并行处理——非常适合批量评审候选方案、从固定的一组材料中提取统一字段、横向比对多份独立判断,或是先多路并行核验再集中汇总结论。

Workflow 从当前会话发起后立即返回 run_id,运行期间不会阻塞当前聊天窗口,你可以照常与主 Agent 交流其他事项。待整套 Workflow 执行完毕或异常中止后,Ankole 会自动唤醒原会话,交由主 Agent 读取汇总结果并继续后续跟进。

选择合适的执行方式

任务特征 推荐方式 选择理由
依赖当前聊天上下文且很快就能完成的短任务 主对话 Agent 回合 直接沿用当前对话上下文,并可使用主回合的完整工具集。
数量有限的独立核验任务,或阶段固定的分步综合分析 Workflow 并行调度多个上下文隔离的有界子 Agent,最终收敛返回一份汇总结果。
需要读写文件、使用沙箱工作区、中途接收补充指令或人工确认的长耗时有状态任务 后台 Agent 任务 拥有可随时挂起、引导与断点恢复的持久化 Codex 线程及独立工作区。
由定时计划或 Webhook 触发的纯确定性机械处理 Automation Job 无需消耗模型推理判断时,触发器可直接在 Function Runtime 中执行 Applet Action。

Workflow 的编排程序在启动后固定,子任务不能直接订阅外部 Webhook 或调用 clarify。需要主 Agent 决策时,子任务可调用带 attention: true 的 sleep,再通过任务消息接收答复。需要可编辑工作区与交互执行线程的工作,应使用后台 Agent 任务。

让 Agent 启动 Workflow

只需在聊天指令中交代清楚有限的输入范围、每个子任务的职责、完结判定标准及最终输出格式即可。例如:

请把这项工作作为 Workflow 执行。按下面五项标准并行评审这 40 份方案,
返回一份 JSON 结果,包含每份方案的结论、失败的评审和最终候选名单。
不要把范围扩大到这 40 份方案之外。

收到请求后,主 Agent 会自行编写编排脚本并提交运行,无需你手写一行 JavaScript 或手工调用接口。发起运行时,主 Agent 可按需指定本次运行的并发度、允许调用的子 Agent 总次数上限,以及整场运行的默认 model_profile(可选用当前可解析的 light、primary、heavy 能力档位或已命名的自定义模型档案,未显式指定时默认为 primary);编排脚本内的单次 agent(prompt, options) 调用也可通过 options.model_profile 按阶段独立选择模型档位。

成功拉起后,主 Agent 会立即拿到运行 ID 与初始的 running 状态,无需在原地死等轮询;你既可以在当前对话中继续聊别的话题,也可稍后随时主动询问进展。

编排程序怎样运行

编排程序读取创建时冻结传入的 JSON 参数对象 args,并通过调用 agent(prompt, options) 派发子任务:放进 Promise.all 中的一组调用会并发推进;待上一阶段全部返回后,普通的 JavaScript 条件分支即可根据中间结果决定是否继续进入交叉核验或最终汇总阶段。所有数组遍历与循环都必须具备明确、有限的次数上界。

下面这段简化示例演示了最多并行评审 20 个条目、将重试耗尽失败的条目保留为 null,最后再将所有成功结果汇总成篇的典型写法:

const items = args.items.slice(0, 20)
const reviews = await Promise.all(
  items.map(item =>
    agent(`评审此项目:${JSON.stringify(item)}`, {
      label: `review-${item.id}`,
      schema: {
        type: 'object',
        properties: {
          id: { type: 'string' },
          verdict: { type: 'string', enum: ['accept', 'reject'] },
          reason: { type: 'string' }
        },
        required: ['id', 'verdict', 'reason'],
        additionalProperties: false
      }
    })
  )
)

const successful = reviews.filter(review => review !== null)
const summary = await agent(`汇总这些评审:${JSON.stringify(successful)}`, {
  label: 'summary'
})

return { reviews, summary }

运行一旦启动,编排源码与初始 args 即被锁定不可更改。每推进一个编排步骤,控制面都会将其发往无状态的 ankole-function-runtime 服务(调用 POST /v1/program/run):每一步均在全新拉起的隔离运行时实例中求值,彻底封禁网络访问、文件系统读写、环境变量读取、子进程拉起及原生 FFI 权限,并固定注入确定性的 Math.random() 与 Date.now() 实现;在等待子 Agent 执行推理期间,该脚本运行时会立即释放退出,不会占着内存常驻空等。

当控制面发生重启恢复时,系统会在 6 MiB 的持久化记忆(Memo)缓存预算内,结合已落库保存的子任务结果从头确定性重放整段编排程序:此前已成功落库的子任务会直接命中缓存跳过重建;倘若重放过程中产生的 agent() 调用顺序或入参内容与历史记录对不上,整次运行便会直接报错中止。至于重启瞬间恰好被打断的在途子任务则会重新发起尝试,因此请勿将子任务理解为“严格至多执行一次”。

每个子 Agent 可以访问什么

每次 agent() 调用都在控制面上的独立隔离会话(wf_task:<call_id>)内执行,不占用该 Agent 的 Worker 沙箱槽位。子 Agent 会继承所属 Agent 的基本身份、AGENTS.md 以及本次传入的专项任务提示词,但不会继承原主会话的冗长聊天上下文;除非编排程序显式将上一阶段的输出拼入下一阶段的提示词中,否则各个并行子任务之间彼此完全隔离、互不可见。

在工具权限上,Workflow 子任务可直接调用联网搜索与网页读取工具;若实例已启用 Brain,还可调用只读的 recall 与 entity 检索企业知识。子任务无法直接使用 Shell 终端、沙箱文件读写、MCP、Skill、Brain 写入或定时调度工具,也不允许在内部再次嵌套发起新的 Workflow(编排嵌套深度固定锁死为 1)。

如果某个子任务确实需要沙箱工作区操作或长达数小时的深度处理,它可以转而委派给后台 Agent 任务(通过 create_background_job、show_background_job_details、send_message_to_background_job 与 stop_background_job),随后调用 sleep 进入无槽位占用的休眠状态(单次休眠时长为 1 分钟至 48 小时,单个子任务最多可休眠 16 次)——直到所委派后台任务产生生命周期变更、主会话主动发来补充消息或休眠倒计时到期时再自动恢复执行。若在调用 sleep 时传入 attention: true,系统还会主动提醒主对话 Agent 查阅休眠备注并给予答复。待最终产出准备就绪后,子任务调用 submit_result 提交结构化结果并圆满收尾。

在每一个唤醒执行段内,单次 agent() 调用最多允许进行 3 次任务尝试:一旦成功提交即返回校验后的结果值;若连续 3 次尝试均告耗尽,则该次 agent() 调用在编排程序中返回 null——编排脚本既可过滤掉 null 继续推进后续汇总,也可在最终输出中如实注明缺失项,单个子任务失败并不会连带拖垮整场 Workflow。

要求结构化结果

调用 agent() 时可通过 schema 选项约束返回结构:Ankole 会开启上游模型提供商的严格结构化模式(strict mode)下发动态生成的 submit_result 工具定义,并在控制面收到提交值时做二次严格校验。即使某次提交未通过 Schema 校验也不会直接终止子任务,子 Agent 可对照校验报错自行修正后重新调用提交。

此处支持的 Schema 为 OpenAPI 3 JSON Schema 的受限封闭子集,而非完整规范:每个字段仅支持单一非空基础类型(object、array、string、number、integer 或 boolean);包括嵌套层级在内的每一个 object 都必须显式声明 properties、在 required 数组中列全所有属性名,并固定设置 additionalProperties: false;不支持可选对象属性、nullable、联合类型(union)、$ref 引用,也不支持 oneOf、anyOf 或 allOf 组合关键字。

若未传入 schema,子任务默认返回普通字符串。整段编排程序结束时必须 return 最终汇总结果:返回字符串时会直接作为结果文本交付,返回其他任意合法 JSON 值时则会序列化编码为 JSON 文本。

读取、向任务发消息、列出或取消运行

在主对话中,你可以随时让主 Agent 调用以下配套工具管理 Workflow:

  • show_workflow:查看指定运行的整体状态、各状态子任务计数、最多 32 个活跃子任务详情(含休眠 note、attention 标记与预计唤醒截止时间)、最多 10 条失败原因摘要以及终态错误信息;运行完结后,汇总结果从字节偏移量 0 起分段读取,每段最多返回 8,000 个 UTF-8 字节。
  • send_message_to_workflow_task:按 run_id 与子任务序号 call_seq 异步注入一条来自主会话的指导消息,用于提前唤醒正在休眠的子任务,或答复带有 attention: true 求助标记的子任务。
  • list_workflows:分页列出当前 Agent 名下正在运行或已完结(含 completed、failed、cancelled)的 Workflow 记录,单页最多返回 32 条。
  • cancel_workflow:幂等取消整场运行——先封死新子任务派发并拒绝迟到结果重新激活运行,再通知所有正在执行的子任务回合及其委派出去的后台 Agent 任务一并停止(当时已经发往上游模型的在途单次请求可能需要片刻才会彻底终止)。

Workflow 正常完结或异常失败时都会自动唤醒原主会话;而手动执行取消操作则不会额外推送完结唤醒事件——如需确认是否已彻底停稳,可让主 Agent 再次调用状态查询确认。

在管理后台 Console 首页的“后台活动”面板中,具备 site_console:agent:<agent_uid>:workflow 权限的运维人员可以查看只读的 Workflow 实时监控视图(展示活跃子任务、状态分布计数、休眠备注、到期时间、attention 求助标记及脱敏错误摘要);而发起新运行、向子任务发送消息、读取完整结果正文及取消运行等主动操作,均统一通过主对话 Agent 的 Workflow 工具完成。

控制成本和容量

每一次子任务尝试都对应一轮完整的模型推理回合,期间还可能触发按次计费的联网检索调用——调高并发度只能缩短整批任务的总耗时(挂钟时间),并不能减少总的模型与工具调用次数。因此,请务必结合已知输入规模合理设定调用上限,并尽量保持各子任务的提示词与返回结构精炼紧凑。

配额与体积边界 默认值 系统硬上限
单次 Workflow 运行的最大并发子任务数 8 32
单个 Agent 全局同时运行中的 Workflow 子任务总数 8 64
单次 Workflow 运行允许派发的子 Agent 调用总数 32 1,024
单个唤醒段内的子任务最大尝试次数 最多 3 3
单次子 Agent 调用允许累计休眠的最大次数 — 16
单次休眠的合法时长范围 — 1 分钟至 48 小时
持久化保存的编排程序源码体积 — 256 KiB
持久化保存的初始 args 体积 — 64 KiB
单次 agent() 调用选项与参数对象体积 — 8 KiB
单条主会话注入子任务的消息体积 — 8 KiB
单个子任务单次 submit_result 提交值体积 — 24 KiB
单次运行的持久化重放缓存(Memo)总预算 — 6 MiB
编排程序最终返回的汇总结果体积 — 1 MiB

站点管理员可在 AppConfigure 中在不突破系统硬上限的前提下调整上表前三项实例默认配额;单次运行请求中的并发度和调用次数若在合法范围内,保存时会裁剪至配置上限;超出系统硬性范围的值会被拒绝。此外,Workflow 层不设笼统覆盖整批任务的全局 Token 或金额硬顶,每个子任务回合依然各自受常规回合的最大迭代轮数、单次最大输出 Token 数及无活动闲置超时约束,成本治理策略详见 成本管理。

如果某次运行触及了上述存储或缓存体积上限,建议缩减单次并发扇出(fan-out)规模、要求各子任务仅返回精炼摘要,或将大批量输入切分为多场独立的 Workflow 分批处理。一旦需要修改编排代码逻辑或更换输入参数,请直接发起一场全新的 Workflow 运行——已失败的运行不支持中途替换脚本代码原地续跑。