控制平面与 Agent 协作模式

1. 为什么这组知识要一起学

建立 Agent、Workflow、Harness 与 Runtime 的统一心智模型，先分清决策、执行、状态和控制边界，再进入具体组件。

这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。

2. Mental Model

把模型视为非确定性决策器，把 Harness 视为提供上下文、能力和约束的外壳，把 Runtime 视为真正持有执行权的内核。

User Request → Context → Model Decision → Runtime Validation → Action/Tool → Observation → State Update → Continue/Finish

3. 核心机制

Control Plane vs Execution Plane

控制面保存 policy、routing、configuration、identity 等决策；执行面真正运行 tool/command。分离后可以在不让模型获得控制面凭证的情况下扩展执行能力。

Brain / Hands / Session 分离

Brain 表示推理/决策，Hands 表示 workspace、shell、browser 等执行环境，Session/State 提供连续性。分离这些边界可以独立升级模型、执行环境和持久化策略。

Single Agent / Manager / Handoff / Agent-as-Tool

这四种形态的核心差别是谁持有对话控制权与最终上下文。Single Agent 自己完成任务；Manager 通过 specialist-as-tool 收集结果后仍由 manager 合成；Handoff 把当前控制权转给 specialist；Agent-as-Tool 把子 Agent 当作有输入输出契约的能力。不要因为用了多个模型调用就自动称为 Multi-Agent。

4. 最小实现 / 伪代码

下面代码只表达边界和生命周期，不要求照抄到项目中：

async def run(agent, state):
    while not state.done:
        decision = await agent.decide(state)
        action = runtime.validate(decision)
        observation = await runtime.execute(action)
        state = runtime.reduce(state, observation)

真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。

5. 在 Shadow Harness 中怎么落地

在 Shadow Harness 中，AgentDefinition 只描述 instructions/tools/policies；RunState、Turn、ToolExecution、Checkpoint 等运行事实由 Runtime 单独管理。

建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。

6. Production Engineering 检查项

• 明确终止条件与 max turns
• 区分模型决策与程序事实
• 复杂度随任务需要递增
• 把可替换策略与稳定接口分开

7. Failure Modes

7.1 把固定 Workflow 误叫成自主 Agent

当出现「把固定 Workflow 误叫成自主 Agent」时，检查控制权是否放错层、终止/预算是否缺失，以及 complexity 是否超出任务真实需要。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.2 把重试、权限、状态转换交给模型

当出现「把重试、权限、状态转换交给模型」时，检查控制权是否放错层、终止/预算是否缺失，以及 complexity 是否超出任务真实需要。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.3 一开始就做复杂 Multi-Agent

当出现「一开始就做复杂 Multi-Agent」时，检查控制权是否放错层、终止/预算是否缺失，以及 complexity 是否超出任务真实需要。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.4 Harness 编码了过时的模型能力假设

当出现「Harness 编码了过时的模型能力假设」时，检查控制权是否放错层、终止/预算是否缺失，以及 complexity 是否超出任务真实需要。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

8. Trade-offs

固定 Workflow 可控但灵活性低；纯 Agent 灵活但成本与行为波动大；生产系统常采用 Hybrid。

设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。

9. Experiment / Evaluation

对同一任务分别用固定 Workflow、Agent Loop、Hybrid 实现，比较成功率、turn 数、token、人工介入和失败可解释性。

实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。

10. 常见问题

基础：Control Plane vs Execution Plane 最容易被误解的点是什么？

控制面保存 policy、routing、configuration、identity 等决策；执行面真正运行 tool/command。分离后可以在不让模型获得控制面凭证的情况下扩展执行能力。

机制：这些能力在一次 Run 的哪个生命周期阶段生效？

沿着 User Request → Context → Model Decision → Runtime Validation → Action/Tool → Observation → State Update → Continue/Finish 找位置，并明确它的输入、输出、持久化事实和失败传播。

工程：如果这一层失败，应该由谁恢复？

先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。

设计：规模扩大 10 倍后，哪个假设最先失效？

优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。

11. Sources

• Anthropic — Building effective agents
• Anthropic — Scaling Managed Agents: Decoupling the brain from the hands
• OpenAI Agents SDK — Agents
• OpenAI Agents SDK — Agent orchestration

12. 本文结论

掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。