并行多 Agent 分发 API 参考¶
English · 简体中文
源码真相:
lib/core/runtime.ml、lib/core/types.ml、lib/core/workflow_engine.ml。
本文档涵盖 Runtime.invoke_parallel,这是在单个 Runtime 内并发分发多个 Agent 的便捷 API。每个 Agent 在独立的 Eio fiber 中运行,拥有隔离的工具注册表,结果会被收集并可选择性合并。
概览¶
并行分发解决了"扇出-扇入"模式:对 N 个 Agent 运行不同输入(或相同输入不同配置),收集结果,合并为单一输出。这是 LangGraph Send 或 CrewAI and_() 的 OCaml 等价物。
val Runtime.invoke_parallel :
rt:runtime ->
specs:agent_dispatch_spec list ->
?parallel_limit:int ->
?failure_policy:failure_policy ->
?merge_fn:(Yojson.Safe.t list -> Yojson.Safe.t) ->
?cancellation_token:cancellation_token ->
unit ->
parallel_invoke_result
关于
cancellation_token:这是 record 类型Types.cancellation_token = { switch : Eio.Switch.t; cancelled : bool Atomic.t; reason : cancel_reason option Atomic.t },不是裸的Eio.Switch.t。 用Cancellation.create_token构造。运行时读取原子标志,并在请求取消时停止内嵌的switch。详见下文「取消」一节。
agent_dispatch_spec¶
每个 Agent 的并行分发配置:
type agent_dispatch_spec = {
agent_id : string;
input : string option;
workspace : Workspace.workspace option;
approval_handler : Approval.approval_handler option;
blocking_approval : bool;
conversation : conversation option;
}
| 字段 | 描述 |
|---|---|
agent_id |
必填。要分发的 Agent(必须通过 make_agent 注册)。 |
input |
可选的 prompt 覆盖。如果为 None,Agent 使用默认行为。 |
workspace |
可选的每 Agent 工作空间。覆盖运行时级别的工作空间,用于该 Agent 的工具处理器。适用于将并行 Agent 沙箱化到不同的文件系统根目录。 |
approval_handler |
可选的每 Agent 处理器覆盖。当同时存在 agent_config 上的处理器时,优先使用此处的处理器。 |
blocking_approval |
预留给未来版本;当前 beta 的 invoke_parallel 不读取该字段。所有分支目前都独立挂起。 |
conversation |
从已有对话开始该分支。None 表示新建。更新后的分支对话通过 parallel_success.conversation 返回。 |
parallel_invoke_result¶
所有分支完成(或 Fail_fast 停止它们)后返回:
type parallel_success = {
spec : agent_dispatch_spec;
result : Yojson.Safe.t;
conversation : conversation;
}
type parallel_invoke_result = {
successes : parallel_success list;
failures : (agent_dispatch_spec * error_category) list;
merged : Yojson.Safe.t option;
}
| 字段 | 描述 |
|---|---|
successes |
每个成功分支一条记录。result 是该 Agent 的原始 JSON 结果 —— 不是 invoke_result record。conversation 是分支更新后的历史;如果 spec 提供了输入对话,它也会包含在内。 |
failures |
失败的 Agent 的 (agent_dispatch_spec, error_category) 元组列表。 |
merged |
merge_fn 对成功结果的合并输出;未提供 merge_fn 时为 None。 |
控制并行度¶
parallel_limit¶
通过 Eio.Semaphore 控制最大并发 Agent 数:
当限制小于 spec 数量时,Agent 会排队,等待可用插槽。
failure_policy¶
复用工作流引擎的 failure_policy:
type failure_policy =
| Fail_fast (* 遇到第一个错误停止 *)
| Continue_on_failure (* 跳过失败步骤,继续运行 *)
| Conditional of { on_failure : workflow_step } (* 失败时运行补偿步骤 *)
| 策略 | 行为 |
|---|---|
Fail_fast |
第一个错误停止所有分支,剩余分支被取消。 |
Continue_on_failure |
跳过失败分支。只有成功的结果出现在 successes 中。 |
Conditional |
失败时运行 on_failure 步骤(例如,后备 Agent、清理)。 |
使用 merge_fn 合并结果¶
merge_fn 参数让你将分支结果组合为单一输出,类似 LangGraph 的 reducer 模式:
(* 默认:将结果包装在 JSON 列表中 *)
let default_merge (results : Yojson.Safe.t list) = `List results
(* 自定义:连接文本输出(假设每个 Agent 返回 `Assoc 且含 "text" 字段)*)
let concat_merge (results : Yojson.Safe.t list) =
let texts = List.filter_map (fun json ->
match json with
| `Assoc fields ->
(match List.assoc_opt "text" fields with
| Some (`String t) -> Some t
| _ -> None)
| _ -> None
) results in
`String (String.concat "\n---\n" texts)
(* 自定义:计数成功 *)
let count_merge (results : Yojson.Safe.t list) = `Int (List.length results)
如果未提供 merge_fn,结果被包装在 JSON 列表中(\List [...]`)。
let result =
Runtime.invoke_parallel ~rt
~specs:[
{ agent_id = "summarizer"; input = Some "Summarize doc A"; ... };
{ agent_id = "summarizer"; input = Some "Summarize doc B"; ... };
{ agent_id = "summarizer"; input = Some "Summarize doc C"; ... };
]
~merge_fn:concat_merge
()
in
(* 直接迭代 parallel_success 记录 —— 没有 `merged` 字段 *)
List.iter (fun s ->
Logs.info (fun m -> m "agent %s: %s"
s.spec.agent_id (Yojson.Safe.to_string s.result))
) result.successes
分支对话¶
传 conversation 让分支从已有历史开始;通过 parallel_success.conversation 接管胜出分支:
let specs = [
{ agent_id = "analyst"; input = Some "Continue the investigation";
conversation = Some prior_conversation; workspace = None;
approval_handler = None; blocking_approval = false };
] in
match Runtime.invoke_parallel ~rt ~specs () with
| Ok { successes = [winner]; _ } ->
(* winner 的历史现在包含 prior_conversation + 本轮新消息。 *)
Runtime.save_conversation rt ~conversation:winner.conversation
~scope:"investigation" ()
| Ok _ -> ()
| Error e -> ...
invoke_parallel 不会自动保存分支对话;由调用方决定是否持久化胜出者。
每 Agent 工作空间隔离¶
每个并行分支都有自己的 per_call_registry(工具注册表)。如果在 spec 上提供 workspace,该 Agent 的工具在不同的文件系统根目录下运行:
let spec_a =
{ agent_id = "reader"; input = Some "Read /project-a/README.md";
workspace = Some (Workspace.create "/project-a"); ... }
in
let spec_b =
{ agent_id = "reader"; input = Some "Read /project-b/README.md";
workspace = Some (Workspace.create "/project-b"); ... }
in
(* 每个 Agent 只看到自己的工作空间 *)
当 workspace 为 None 时,Agent 使用运行时级别的工作空间。
HITL x 并行交互¶
并行分发与 HITL 框架 集成:
- 非阻塞(默认):如果 Agent 通过 async 或 webhook 处理器触发审批,只有该分支挂起。其他分支继续运行。
- 阻塞(
blocking_approval = true):预留给未来版本;当前 beta 的invoke_parallel不读取该字段。所有分支目前都独立挂起。 - 每 Agent 处理器:每个 spec 可以覆盖审批处理器。这意味着同一批并行中的不同 Agent 可以使用不同的审批策略。
let specs = [
{ agent_id = "safe_agent"; input = Some "Analyze data";
approval_handler = None; blocking_approval = false; conversation = None; ... };
{ agent_id = "risky_agent"; input = Some "Send notification";
approval_handler = Some webhook_handler;
blocking_approval = false; conversation = None; ... }; (* 独立挂起 *)
]
取消¶
传递 cancellation_token(即 Types 中的 record { switch : Eio.Switch.t; cancelled : bool Atomic.t; reason : cancel_reason option Atomic.t },通常用 Cancellation.create_token 构造)来取消所有分支:
Eio.Switch.run (fun cancel_switch ->
(* 将 switch 包装为 cancellation_token record *)
let token = Cancellation.create_token cancel_switch in
(* 在后台 fiber 中启动并行分发 *)
let fiber = Eio.Fiber.fork_promise (fun () ->
Runtime.invoke_parallel ~rt ~specs
~cancellation_token:token ())
in
(* 稍后:请求取消 *)
Cancellation.request_cancel token User_cancelled)
取消时,分支停止,部分结果(如果有)被收集。
完整示例¶
open Par
let () = Eio_main.run (fun env ->
Eio.Switch.run (fun switch ->
let config = Runtime.default_config ~persistence:(`Sqlite ":memory:") () in
match Runtime.create ~config switch with
| Error e -> prerr_endline (Runtime.string_of_error_category e)
| Ok rt ->
(* 创建 Agent *)
let summarizer =
Runtime.make_agent ~id:"summarizer" ~model:"openai/gpt-4o-mini" ()
in
let translator =
Runtime.make_agent ~id:"translator" ~model:"openai/gpt-4o-mini" ()
in
ignore (summarizer, translator);
(* 分发 3 个并行摘要任务 *)
let specs = List.map (fun topic ->
Types.{ agent_id = "summarizer";
input = Some ("Summarize: " ^ topic);
workspace = None;
approval_handler = None;
blocking_approval = false;
conversation = None }
) ["AI safety"; "Quantum computing"; "Climate change"]
in
let result =
Runtime.invoke_parallel ~rt ~specs
~failure_policy:Fail_fast
~merge_fn:(fun (results : Yojson.Safe.t list) ->
let texts = List.filter_map (fun json ->
match json with
| `Assoc fields ->
(match List.assoc_opt "text" fields with
| Some (`String t) -> Some t
| _ -> None)
| _ -> None
) results in
`String (String.concat "\n\n" texts))
()
in
Printf.printf "Successes: %d\n" (List.length result.successes);
Printf.printf "Failures: %d\n" (List.length result.failures);
List.iter (fun s ->
Logs.info (fun m -> m "agent %s produced: %s"
s.spec.agent_id (Yojson.Safe.to_string s.result))
) result.successes;
ignore (Runtime.close rt)))
Python 交叉引用¶
Python 绑定通过 ctypes 暴露并行分发。详见 Python FFI 文档:
Runtime.invoke_parallel(specs: list[dict]) -> dict,每个 spec 字典包含agent_id、input、workspace、approval_handler、blocking_approval、conversation键。- 每 Agent 的工作空间和审批处理器覆盖与 OCaml API 行为一致。
与 Workflow API 的关系¶
Runtime.invoke_parallel 是现有 Workflow API Parallel 步骤类型的便捷封装。内部构造一个包含 Parallel 节点的工作流,每个 spec 对应一个 Agent_call,提交后收集结果。
如果你需要更复杂的编排(顺序步骤混合并行、条件分支、检查点),直接使用 Workflow API。如果你只需要"N 个 Agent 并行运行并合并结果",invoke_parallel 是更简单的入口。