Workflow系列04：多智能体协调中的编排器边界、并发控制与上下文隔离

编排器的职责边界

在多智能体工作流的设计中，最常见的问题就是主Agent与子Agent之间的职责划分不清晰。

简而言之，编排器主要负责以下三项任务：

• 决策：读取当前系统状态，判断下一步执行策略
• 分派：创建子Agent实例，并将任务指令传递给它
• 收集：解析子Agent的输出文件，同步更新工作状态

那么，编排器不负责哪些操作？答案同样清晰：

• 不直接参与业务逻辑执行（例如分析Bug、编写代码、查询日志）
• 不直接读取原始日志文件或长文本内容（否则上下文会迅速膨胀）
• 不直接修改业务数据（仅子Agent具备操作权限）

关键在于，主Agent仅接收结构化结论（如JSON格式），而非原始输出。子Agent通过固定的输出文件（例如output.json）向主Agent汇报，而非依赖消息流传递。

举个例子：

# ✅ 正确做法：主Agent读取结构化结论
result = json.loads(Path("phase3/analysis_final.json").read_text())
if result["confidence"] >= 95:
    proceed_to_phase4()

# ❌ 错误做法：主Agent直接读取原始日志
log_content = Path("crash.log").read_text()  # 10万行日志将直接进入主Agent上下文
decision = llm.analyze(log_content)  # 主Agent不应执行此操作

这种边界划分带来双重好处：主Agent的上下文始终保持可控（仅包含状态与结论，无原始数据）；子Agent的业务逻辑可独立测试，无需依赖主Agent的会话历史。

子Agent的设计原则

原则一：输入完备性

子Agent的任务指令必须包含其完成工作所需的全部信息。

# ❌ 不完备的任务指令示例
分析这个Bug的根因，参考之前的分析结果。

# ✅ 完备的任务指令示例
## 任务
分析以下Bug的根因。
## 输入
Bug信息：{{ bug_info.summary }}{{ bug_info.stack_trace }}
日志目录：{{ log_dir }}
## 输出要求
将结果写入analysis_final.json，格式为：{"confidence": float, "root_cause": str, "evidence": [str]}

“参考之前的分析结果”这种表述依赖于子Agent能够访问主Agent的上下文历史，但在隔离会话中，这一假设并不成立。每个子Agent仅知悉任务指令中明确给出的信息。

原则二：输出契约严格性

子Agent必须依照约定的JSON Schema格式写入输出文件。主Agent依赖此Schema进行路由决策，字段缺失或类型错误均会导致判断逻辑失败。

# 子Agent输出Schema（定义于templates/目录下）
OUTPUT_SCHEMA = {
    "passed": bool,      # 必填，主Agent路由决策依赖
    "confidence": float, # 必填，范围0-1
    "root_cause": str,   # 必填
    "evidence": list[str], # 必填
    "error": str | None  # 失败时填写
}

原则三：失败时写入结构化错误信息

即使子Agent执行失败，也必须向输出文件写入内容，仅需将passed设置为false。

// 失败时的输出示例
{
    "passed": false,
    "error": "日志文件不存在：/workspace/logs/crash_20260601.log",
    "confidence": 0,
    "root_cause": null,
    "evidence": []
}

若失败时不写入输出文件，主Agent将误判子Agent超时，从而触发超时处理逻辑。结构化的错误信息使主Agent能够区分“子Agent失败”与“子Agent超时”，进而采取不同的应对策略。

Fan-out / Fan-in 并发控制

Fan-out设计

Fan-out指的是从一个触发点生成N个并发子Agent。需遵循两个关键约束：

约束1：每个子Agent应写入不同的输出文件路径

# ✅ 正确做法：每个候选写入独立文件
candidates = ["candidate_a", "candidate_b", "candidate_c"]
for c in candidates:
    spawn_subagent(task_prompt=build_prompt(c, bug_info),
                   output_file=f"phase4/{c}.json")  # 文件名唯一

# ❌ 错误做法：所有候选写入同一文件（导致并发写入冲突）
spawn_subagent(task_prompt=..., output_file="phase4/result.json")
spawn_subagent(task_prompt=..., output_file="phase4/result.json")  # 冲突！

约束2：主Agent需等待所有子Agent执行完成

Fan-out后，主Agent进入等待状态，暂停执行后续阶段。等待方式取决于系统是否具备异步处理能力。

# 同步等待（轮询模式）
import time
def wait_all_candidates(candidates: list[str], timeout: int = 300) -> dict:
    results = {}
    deadline = time.time() + timeout
    while len(results) < len(candidates) and time.time() < deadline:
        for c in candidates:
            if c not in results:
                output_file = Path(f"phase4/{c}.json")
                if output_file.exists():
                    results[c] = json.loads(output_file.read_text())
        time.sleep(5)
    return results

Fan-in：失败策略选择

Fan-in过程中，若部分子Agent失败，可采用以下两种策略：

fail-fast（快速失败：任一失败即中止）

# 适用场景：所有分支结果均必须成功，任一失败则整体无意义
phase_parallel_analysis:
  fan_in_strategy: fail-fast
  on_any_failure: trigger_gate_A  # 任一失败则触发确认门

适用场景举例：3个子Agent同时从不同数据源获取数据，缺少任一数据源均无法继续分析。

collect-all（全部收集：汇总所有结果，包含失败项）

# 适用场景：部分失败仍有价值，选用成功的结果
phase_4_fix:
  fan_in_strategy: collect-all
  selection_criteria:
    require_any_passed: true       # 至少1个通过才继续
    select_by: max_test_coverage   # 从通过的候选里选覆盖率最高的
    on_all_failed: trigger_gate_B  # 全部失败才触发确认门

适用场景举例：3个代码修复候选方案并发执行，只需其中一个通过测试即可，失败候选直接丢弃。

选择原则

所有分支结果缺一不可 → 选择fail-fast
部分成功即可继续 → collect-all（代码修复、生成候选）
需要比较多个结果质量 → collect-all（比较后选优）

以Bug修复工作流为例：Phase 4采用collect-all策略，3个修复候选并发执行，从中选择通过单元测试且代码覆盖率最高的方案。仅当全部3个候选均失败时，才触发人工确认门。

上下文隔离

子Agent必须在隔离的会话环境中运行，无法访问主Agent的对话历史。

主Agent的上下文包含工作流的完整历史记录，包括所有文件内容、所有子Agent的原始输出以及所有中间决策。若将这些信息全部传递给一个专注于“编写修复代码”的子Agent，将会导致：

• 子Agent的上下文从几K tokens膨胀至几十K tokens
• 大量无关信息干扰子Agent的注意力，导致输出质量下降
• Token消耗成本翻倍
• 子Agent更容易被主Agent历史中的“噪声”误导

信息仅沿两个方向流动：

主Agent
│
│ task prompt（只包含子Agent需要的字段）
▼
子Agent（隔离会话，无历史记录）
│
│ output_file（约定路径的JSON文件）
▼
主Agent（读取文件，不读对话历史）

子Agent只知悉任务指令中给出的内容，以及约定的输出路径。它不知道主Agent已执行的操作，不了解其他子Agent的结果，也不知晓工作流当前进行到哪一步。

若子Agent需要“了解背景”才能完成任务，则表明任务指令不够完备。正确的做法是将背景信息显式写入指令中，而非让子Agent访问主Agent的历史记录。

设计Checklist

Orchestrator职责

• 主Agent仅读取结构化JSON输出，不直接读取原始日志或长文本
• 主Agent不直接执行业务逻辑（如分析、写代码、查询等）
• 路由决策依赖状态文件与子Agent输出，不依赖对话历史

子Agent设计

• 任务指令包含子Agent完成任务所需的所有字段（不依赖隐含上下文）
• 输出Schema在templates/目录中明确声明，包含passed字段
• 失败时仍写入{"passed": false, "error": "..."}格式的输出文件

并发控制

• Fan-out时每个子Agent应写入不同路径的输出文件
• Fan-in策略需明确标注为fail-fast或collect-all
• collect-all策略需明确定义selection_criteria与on_all_failed行为

上下文隔离

• 子Agent在独立会话中运行，不访问主Agent的对话历史
• 子Agent所需的背景信息均显式写入任务指令中

总结

1. 编排器仅负责决策与分派：读取JSON结论、生成子Agent、收集JSON结论，不执行具体业务——核心目的是保持上下文可控。
2. Fan-in策略决定工作流的韧性：对于代码修复这类“解空间多样”的场景，采用collect-all策略，仅在全部失败时才升级人工处理；对于数据收集这类“缺一不可”的场景，采用fail-fast策略，任一失败即触发异常处理。
3. 上下文隔离是质量保证：子Agent仅知晓任务指令中的内容，多余的上下文是干扰而非帮助；若子Agent需要“了解背景”，应在任务指令中显式提供该背景信息。