多智能体的失败很少发生在"模型不够强"，而是发生在拓扑没定清：谁有权决策、上下文在哪一层被裁掉、任务交接时丢了哪几个字段。这三件事没写进代码，就一定在凌晨的日志里出现。这篇把四种常见拓扑摆出来对照，然后往下钻到交接协议与长任务检查点。

1. 四种拓扑的定位

判断顺序是：任务能不能并行 → 质量有没有可判定标准 → 上下文会不会超窗。三个都否，就该老实写 Single-Agent。

2. Single-Agent：工具超过八个就开始选错

def run_single(task, tools, max_steps=12):
    ctx = [{"role": "user", "content": task}]
    for step in range(max_steps):
        msg = llm(ctx, tools=tools, tool_choice="auto")
        ctx.append(msg)
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            ctx.append(exec_tool(call, tools))   # 结果以 tool 角色回填
    return "step_budget_exhausted"

工具描述的质量比工具数量更决定成败。两个名字相近、描述都写"查询数据"的工具，模型必然误选。

3. Orchestrator-Workers：扇出容易，汇聚难

import asyncio

async def orchestrate(goal, plan, workers):
    subs = plan(goal)                       # [{id, task, worker}]
    results = await asyncio.gather(*[
        workers[s["worker"]].run(s["task"]) for s in subs
    ], return_exceptions=True)
    ok = [r for r in results if not isinstance(r, Exception)]
    if len(ok) < len(subs) * 0.6:           # 汇聚前先判完成率
        return {"status": "partial", "results": ok}
    return {"status": "ok", "merged": merge(goal, ok)}

扇出数要有上限。子任务从 5 涨到 20，延迟不一定涨，但 token 成本线性涨，而质量在第 8 个之后基本不动。

4. Evaluator-Optimizer：两个角色、一个终止条件

评审意见必须能被验证。写"表达可以更清晰"等于没写；写"第 3 条缺少失败时的返回值说明"才是可执行反馈。

def optimize_loop(task, gen, review, max_rounds=3):
    draft, prev_issues = gen(task), None
    for r in range(max_rounds):
        ok, issues = review(draft)
        if ok:
            return draft, r
        if issues == prev_issues:            # 同一批问题反复出现 → 死锁
            return draft, r
        prev_issues = issues
        draft = gen(task, fix=issues)        # 只修被指出的问题
    return draft, max_rounds

5. Sub-Agent：上下文隔离是买来的，不是免费的

Parent-Child 的核心动作是派生一个带独立上下文的子代理，只回传结论。它买到的是预算隔离，付出的是信息丢失。

典型误用：把"需要主代理已知的约束"放在子代理内部，结果子代理产出不满足约束的方案，主代理还得再审一遍——这就等于付了隔离成本却没得到隔离收益。

6. Parent-Child 交接协议：字段比措辞重要

{
  "handoff_id": "h-2026-0017",
  "parent_id": "root",
  "child_id": "worker-extract",
  "objective": "从附件中抽取全部付款条款，输出 JSON 数组",
  "constraints": ["金额保留两位小数", "缺失字段填 null，不要猜"],
  "inputs": {"file": "contract.pdf", "pages": "12-18"},
  "output_schema": {"type": "array", "items": {"type": "object"}},
  "budget": {"max_steps": 8, "max_tokens": 6000, "deadline_s": 90},
  "return": {"must_include": ["result", "steps_used", "unresolved"]}
}

unresolved 这个字段价值极高：它把"子代理遇到的问题"变成结构化数据，父代理才能决定重试、换工具还是上报人。

7. Long-Running 任务：检查点与外置草稿

长任务的失败模式不是"算错"，而是"跑到第 40 步时进程没了，全部重来"。解法是把状态落到文件系统，而不是留在上下文里。

import json, os, pathlib

STATE = pathlib.Path("/work/run-state.json")

def checkpoint(step, plan, done, notes):
    tmp = STATE.with_suffix(".tmp")
    tmp.write_text(json.dumps(
        {"step": step, "plan": plan, "done": done, "notes": notes},
        ensure_ascii=False), encoding="utf-8")
    os.replace(tmp, STATE)          # 原子替换，避免半写文件

def resume():
    if STATE.exists():
        return json.loads(STATE.read_text(encoding="utf-8"))
    return {"step": 0, "plan": [], "done": [], "notes": []}

Planning-with-Files 的要点是计划本身也是一个文件：每步完成后回写状态与下一步，恢复时只读计划，不读全部历史。这让"第 41 步重启"的成本从"重跑 40 步"降到"读一个文件"。

8. Code-as-Action 与工具调用的分工

判据：动作是"一件事"就用工具，是"一串事"就写代码。让模型连续调用六个工具做数据清洗，既慢又容易在中间步骤丢字段；给它一个能执行代码的沙箱反而更省。

9. Meta-Agent：什么时候才值得多一层

Meta-Agent 指"负责设计/调度其他代理的代理"。它只在两种情况下有价值：拓扑本身要随任务变化，或者代理数量已经多到人工配置不动。

引入后必须同时引入拓扑审计：记录每次生成的拓扑与实际执行路径，否则出错时无法归因。

10. 排错：六种协作失效

11. 边界：这些情况不该拆多代理

12. 自测

1. 什么时候该从 Single-Agent 升级到 Orchestrator-Workers？判断依据是什么？
2. Evaluator-Optimizer 里，"连续两轮问题集合相同"为什么可以判为死锁？
3. Sub-Agent 隔离上下文的代价具体是哪一项？什么情况下等于白付这个成本？
4. 交接体里 unresolved 字段解决的是什么问题？缺了会怎样？
5. Planning-with-Files 让"第 41 步重启"变便宜，靠的是哪个设计取舍？
6. Code-as-Action 相比 Tool Call，多出来的安全与审计成本分别落在哪？