Agent Loop 与 Harness 架构 ​

本篇边界：这里只回答“智能体怎样形成反馈循环，以及生产系统怎样控制这个循环”。Context（模型上下文）只讲模型这一轮需要看到什么；Runtime（运行时）只讲 Run（运行实例）怎样跨故障继续；Execution（执行层）只讲动作在哪里真实发生；Memory（记忆）、Multi-Agent（多智能体）与 Protocol（协议）均不在本篇展开。这样可以避免 Harness 变成吞掉所有能力的超级抽象。

一、Agent Loop 到底是什么 ​

1.1 Agent Loop 到底解决什么问题 ​

核心结论 ​

这一篇只聚焦两个问题：

Agent 为什么能够持续执行复杂任务？
围绕这个 Loop，生产系统为什么需要 Harness？

Context Engineering（上下文工程）、Runtime（运行时）、Execution Infrastructure（执行基础设施）、Memory / Skill（记忆 / 技能）、Multi-Agent（多智能体）、Protocol（协议）会在后续专项继续深入；本文只讲它们与 Loop / Harness 的必要边界。

Agent Loop（智能体循环）是现代 Agent 的最小反馈运行机制：

当前状态
→ 模型决策
→ 执行动作
→ 获取环境反馈
→ 更新状态
→ 再次决策

它和普通 LLM（大语言模型）应用最大的区别，不是“调用了 Tool（工具）”，而是：

外部世界的执行结果会重新进入下一轮决策。

因此：

Tool Calling（工具调用）
≠
Agent Loop（智能体循环）

Tool Calling 解决的是：

模型能不能调用外部能力。

Agent Loop 解决的是：

调用后的结果能不能持续改变后续行为，直到任务真正结束。

最小结构怎样形成反馈闭环 ​

从工程角度，最小 Loop 可以拆成两层。

第一层是 Loop Kernel（循环内核）：

Context Assembly（上下文组装）
→ Decision（决策）
→ Action（行动）
→ Execution（执行）
→ Observation（观察）
→ State Update（状态更新）
→ 下一轮 Context

第二层是 Task / Control Envelope（任务 / 控制外壳）：

Task Contract（任务契约）
Termination（终止条件）
Budget（预算）
Cancellation（取消）
Verification（验证）

这两个层次必须区分。

因为：

• Loop Kernel 负责“每一轮怎么跑”；
• Control Envelope 负责“为什么跑、跑到什么时候、什么算成功”。

核心对象怎样划分 ​

Task Contract（任务契约） ​

Task Contract 是本文采用的工程抽象，并不是所有 Agent Framework（智能体框架）都使用的统一行业名词。它强调的是：在进入自主执行之前，把模糊用户意图转换为可执行、可约束、可验证的任务语义。

定义：

goal
constraints
success_criteria
allowed_scope
deadline
budget

例如：

Goal:
修复登录接口偶发 401

Constraints:
- 不修改数据库 schema
- 不操作 production

Success Criteria:
- auth tests 全部通过
- build 成功
- 无新增 lint error

企业级 Agent 不应该只有一个模糊 Prompt：

“帮我修好。”

而应该逐步升级成可执行、可验证的任务契约。

Run State（运行状态） ​

State 是系统真实保存的执行状态，例如：

当前步骤
已执行 Tool
Tool Result
Artifact
当前 Plan
预算消耗
审批状态
失败次数

要特别注意：

State ≠ Context。

State 是系统知道什么。

Context 是：

这一轮模型被允许看到什么。

Context（模型上下文） ​

Context 可以来自：

Task Contract
+ Relevant Run State
+ Session History
+ Files
+ Knowledge
+ Memory
+ Skills
+ Tool Observations

但并不是所有 State 都应该进入模型。

更准确的关系：

Run State + External Sources
        ↓
Context Selection / Assembly
        ↓
Model Context

这个边界是后续 Context Engineering（上下文工程）的基础。

Decision（决策）

Decision 不只是：

调用 Tool

完整 Agent Action Model（动作模型）可以包括：

Tool Call
Text Response
Plan Update
Handoff
Spawn Subagent
Ask User
Finish Request

所以：

Tool Call 是 Agent Action 的一种，不是全部。

Action Proposal（动作提议） ​

模型输出 Action 只表示：

模型希望系统执行什么。

它并不代表真实世界已经发生变化。

因此生产系统应该明确区分：

Decision
→ Action Proposal
→ Policy / Permission
→ Execution
→ Raw Result

例如：

delete_file("/prod/config")

在模型层只是 Action Proposal。

真正执行之前仍然需要：

Schema Validation
Identity Check
Resource Permission
Risk Policy
Human Approval（必要时）

这个边界是 Agent Security（智能体安全）和 Controllability（可控性）的基础。

Observation（观察） ​

Observation 也不等于 Tool Result。

例如：

Shell 原始输出
= 20,000 行日志

真正给下一轮 Agent 的 Observation 可能只是：

exit_code = 1
root_error = dependency conflict
full_log = artifact://run/123/log.txt

因此：

Raw Result
→ Normalize / Summarize
→ Observation
→ State Update

Observation 也不一定只来自 Tool。

常见来源包括：

Environment Observation
→ 文件 / 页面 / 数据库 / API 的真实结果

Policy Observation
→ Action 被 Allow / Ask / Deny 的原因

Verification Observation
→ 哪个 Success Check 没通过

Human Observation
→ 用户澄清、Approval、人工反馈

Subagent Observation
→ 子 Agent 返回的结果

这说明现代 Agent Loop 更准确的抽象不是：

LLM ↔ Tool

而是：

Agent Decision
↔
Environment / Policy / Human / Verifier / Subagent

这是生产 Agent 非常关键的机制。

Observation 也是一个有损的信息投影。它需要缩减原始结果，却不能在缩减时丢掉影响决策的证据。因此一条可审计的 Observation 至少应该保留：

这里的责任边界是：Executor（执行器）返回可对账的原始结果，Harness 把原始结果转成模型可消费的 Observation，Runtime 持久化原始结果、Observation 和它们的关联。不能为了节省 Token（模型输入输出的计量单位），将经过摘要的 Observation 当成唯一事实源。

这四个对象最容易在实现中被混成一个大字段。更稳定的做法是让每个对象都有独立责任和版本语义：

Runtime 负责让这些状态和引用可靠存在，但不取代各对象的语义 Owner。例如 Evidence 是否足以证明成功，仍由领域成功契约和 Verifier 决定，不由持久化系统决定。

Termination（终止）与 Verification（验证） ​

二者必须分开。

Termination 回答：

为什么 Loop 停止？

可能因为：

final output
max_turns
timeout
budget exceeded
cancel
hard failure

Verification 回答：

即使 Loop 想结束，任务真的成功了吗？

例如：

模型：代码已经修好
Verification：tests failed

因此：

model_done
≠
verified_done

二者分开之后，Loop Controller（循环控制器）才能做出不同的结束决策：

因此“停止”不是一个布尔值，而是带有原因、证据和恢复语义的状态转换。

1.2 Agent Loop 与 Tool / Workflow 的边界 ​

先用一张表建立全局区别：

三者不是互斥关系。

真实企业系统经常是：

Workflow
→ 某个节点调用 Agent Loop
→ Agent Loop 内部使用 Tool Calling

因此：

Tool Calling
⊂ Agent 的 Action 能力

Agent Loop
= Feedback-driven Control Flow

Workflow
= Deterministic / Semi-deterministic Control Flow

下面分别再看细节。

普通 Tool Calling：

User
→ Model
→ Tool
→ Result
→ Answer

Agent Loop：

User Goal
→ Model
→ Tool
→ Observation
→ Model
→ Tool
→ Observation
→ ...
→ Verified Finish

关键区别：

环境反馈是否持续改变后续决策。

为什么生产系统通常是 Workflow + Agent ​

Workflow 更像：

Step 1
→ Step 2
→ Step 3

下一步主要由程序预先定义。

Agent Loop：

Current State
→ Model decides next action

更适合：

• 下一步不确定；
• 需要环境反馈；
• 需要多轮试错；
• 无法预先写死完整路径。

1.3 什么时候值得使用 Agent Loop ​

适合：

步骤不确定
+
需要外部环境
+
结果会改变下一步
+
可能需要试错

例如：

• Coding Bug Fix；
• Research；
• Browser Task；
• Data Analysis；
• Incident Diagnosis。

不适合默认 Agent 化的场景：

• 单 Tool 即可完成；
• 固定确定性流程；
• 强事务且步骤已知；
• 极高风险且不能接受自主探索。

更成熟的企业模式通常是：

Deterministic Workflow（确定性工作流）
+
Agentic Decision（Agent 自主决策）

二、为什么需要 Agent Loop ​

2.1 为什么单次生成和工具调用都不够 ​

一次 LLM 生成为什么不够 ​

传统 LLM：

Input
→ Model
→ Output

适合生成和理解。

但真实复杂任务是动态的。

例如 Coding Agent：

搜索代码
→ 修改
→ 测试
→ 失败
→ 读错误
→ 再修改
→ 再测试

每一步都会产生新状态。

所以：

复杂任务不是一次生成，而是一个持续根据世界状态变化来修正策略的过程。

为什么 Tool Calling 仍然不够 ​

Tool Calling 让模型获得：

Read File
Run Shell
Query SQL
Call API
Use Browser

但如果 Tool Result 只用于生成最终答案，没有重新进入下一轮决策，系统仍然不具备真正的持续执行能力。

Agent Loop 的价值就在于：

Action
→ Environment Change
→ Observation
→ New Decision

2.2 Agent Loop 为什么会演进成生产控制结构 ​

反馈循环并不是 LLM 时代才有。

传统智能体、控制系统、强化学习里长期存在：

Observe
→ Decide
→ Act
→ Observe

LLM Agent 的一个重要节点是 ReAct（Reasoning + Acting，推理 + 行动）。ReAct 在 2022 年提交，早于 OpenAI 2023 年 6 月正式发布 Function Calling，因此不能简单把历史写成“Tool Calling 之后才出现 ReAct”。更准确的理解是：Reason + Act 的研究范式与结构化 Tool-use 工程能力分别成熟，后来共同汇合成现代 Agent Loop。[^react][^openai-function-calling]

ReAct 将：

Reasoning
→ Action
→ Observation
→ New Reasoning

交替起来。

随着：

• Function Calling（函数调用）；
• Tool Calling（工具调用）；
• Browser / Shell / File Tool；
• Coding Agent；
• Agent SDK（智能体开发工具包）；

逐渐成熟，这种反馈过程开始被产品化、标准化为现代 Agent Loop。

为什么 Loop 是理解 Agent 的第一性主线 ​

看起来完全不同的 Agent：

Coding Agent
Data Agent
Browser Agent
Research Agent
Ops Agent

都可以还原为：

Context
→ Decide
→ Act
→ Observe
→ Update
→ Continue / Finish

区别主要在：

Context 是什么
Action 是什么
Observation 是什么
Success Criteria 是什么

因此真正理解 Loop，相当于掌握研究所有 Agent 的第一层抽象。

三、Agent Loop 怎样运行 ​

3.1 一次 Loop 怎样被建模和推进 ​

Run、Turn、Step 与 Tool Call ​

企业 Agent 中这几个词很容易混，而且不同框架并没有完全统一的定义。

例如 OpenAI Agents SDK 当前把一个 turn 定义为一次 AI invocation（模型调用，包括这次调用产生的 Tool Calls）；DeepSeek Harness 则公开区分 Turn 与 Step，一个 Turn 可以包含多个 Step。[^openai-runner][^dsh-architecture]

因此本文下面给出的不是“行业唯一标准”，而是一套便于企业架构讨论的统一语义约定：

Run（运行实例） ​

完整任务执行。

User Task
→ Run
→ Success / Failure

Turn（回合） ​

一次模型决策周期。

Model Inference
→ zero or more actions
→ observations

Step（任务步骤） ​

更偏任务语义。

例如：

完成登录模块定位
完成修复
完成测试

Tool Call（工具调用） ​

一次具体外部调用。

关系可以理解成：

Run
 ├─ Turn 1
 │   ├─ Tool Call A
 │   └─ Tool Call B
 ├─ Turn 2
 │   └─ Tool Call C
 └─ ...

一个更严谨的 Agent Loop 伪代码 ​

while controller.should_continue(run):

    context = context_builder.build(
        task=run.task_contract,
        state=run.state,
        sources=external_sources,
    )

    capabilities = capability_router.visible_tools(
        task=run.task_contract,
        identity=run.identity,
        state=run.state,
    )

    decision = model.decide(
        context=context,
        tools=capabilities,
    )

    if decision.is_finish_request():
        result = verifier.verify(run)

        if result.passed:
            run.succeed(result.evidence)
            break

        run.state.add_observation(
            result.to_observation()
        )
        continue

    action = decision.action

    policy = policy_engine.check(
        action=action,
        identity=run.identity,
        state=run.state,
    )

    if not policy.allowed:
        run.state.add_observation(
            policy.to_observation()
        )
        continue

    raw_result = executor.execute(action)

    observation = observation_builder.normalize(
        raw_result
    )

    run.state.apply(observation)

这段代码可以映射成：

context_builder
→ Context Engineering

capability_router
→ Capability Exposure

model.decide
→ Decision

policy_engine
→ Permission / Policy

executor
→ Execution

observation_builder
→ Observation

run.state
→ State

verifier
→ Verification

controller
→ Loop Control

一次完整 Turn（回合）的时序可以进一步画成：

这张时序图有一个重要作用：它把“模型的一次输出”放回完整系统里看。模型只是其中一个决策节点，并不是整个 Agent Runtime。

Loop Controller 怎样推进状态 ​

Loop Controller 同样是本文采用的逻辑架构抽象；不同框架可能把它分散在 Runner、Runtime、Policy、Budget 和 Verifier 中，并不一定存在一个同名类。

但从职责上看，它是很容易被忽略、却非常重要的一层：

它负责：

是否继续
是否 Retry
是否 Re-plan
是否 Ask User
是否请求 Approval
是否 Finish
是否 Fail
是否 Cancel

可以抽象：

type LoopDecision =
  | "CONTINUE"
  | "RETRY"
  | "REPLAN"
  | "ASK_USER"
  | "REQUEST_APPROVAL"
  | "FINISH"
  | "FAIL"
  | "CANCEL";

这让 Loop 是否继续不再完全依赖 Prompt。

Budget（预算）与 Cancellation（取消）也不能只在每轮开始前检查一次。模型调用、长时间 Tool、并行子任务和等待人工审批都可能跨越预算或取消边界。生产实现至少需要三层约束：

关键边界是：Harness 定义什么时候必须停止和什么证据要被保留，Runtime 负责将取消与恢复状态可靠地持久化，Executor 负责尽力中止正在执行的外部动作。对已经提交的副作用，“取消 Run”不等于“撤销现实世界的改变”。

Loop Controller 最好显式状态机化 ​

生产实现中，可以进一步把一次 Run 建模成状态机：

这样做的价值是：

• 状态转换可以审计；
• Retry 不会变成“再问模型一次”；
• Approval 可以明确暂停在某个状态；
• Runtime 可以在状态边界做 Checkpoint（检查点，即为后续恢复保存的一致状态快照）；
• Trace 可以直接映射状态变化。

需要特别注意：

状态机是 Loop 的工程表达，不代表所有 Agent 都必须使用同一套状态枚举。

Retry 与 Idempotency（幂等性） ​

生产 Loop 不能简单写：

Tool failed
→ retry

因为 Tool 可能存在 Side Effect（副作用）。

例如：

send_email()
create_order()
deploy_service()
transfer_money()

如果执行端已经成功、只是响应丢失，直接 Retry 可能造成重复副作用。

所以 Action Contract 最好包含：

operation_id
idempotency_key
side_effect
retry_policy
timeout

典型策略：

read-only transient error
→ safe retry

idempotent write
→ retry with same idempotency key

non-idempotent side effect
→ check execution state before retry

deterministic validation error
→ do not retry, re-plan

这也是为什么成熟 Harness 的 Loop Control 不能只等于 max_turns。

阈值不应来自某个开发者的直觉。它应先由任务风险和历史 Trace（追踪数据）分层，再经离线评测与小流量观测校准。例如高风险写操作可以使用更小的连续失败阈值，而大规模只读检索允许更长的探索。每次触发控制决策时，Trace 都应保留“指标值、阈值版本、任务分类与决策结果”，使误停和放行都能复盘。

为了避免 RETRY ↔ REPLAN、ASK_USER ↔ CONTINUE 之间来回振荡，Loop Controller 还需要三类机制：同一 Failure Fingerprint（失败特征指纹）的最大连续次数；状态切换后的最小观察窗口；同一 Action 只有在新证据、新参数或已证明可安全重试时才能重新执行。连续超过阈值后不再自动切换策略，而是进入询问用户、人工接管或终止状态。

3.2 生产级 Loop 怎样避免无限循环和假完成 ​

Production Loop 的关键性质 ​

这些性质不应该平均对待。

这里的 P0、P1、P2 是生产性质的优先级，不是平台成熟度或投资阶段。更合理的优先级是：

P0：Correctness & Safety
→ 做对，而且不能做出不可接受的事

P1：Reliability & Progress
→ 能稳定向前推进，不陷入异常循环

P2：Efficiency & Economics
→ 在成本、延迟和资源约束下完成

P0：Correctness & Safety（正确性与安全性） ​

Consistency（状态一致性） ​

系统记录：

tool_call = SUCCESS

应该可以关联到真实：

Executor Result
operation_id
timestamp
evidence / artifact

不能：

模型认为成功
→ State 直接写 SUCCESS

Safety（安全性） ​

安全性质回答：

什么事情永远不应该发生？

例如：

未授权 Agent 不得写 production
未经 Approval 不得执行高风险 Action
只读 Agent 不得调用 write Tool

必须由模型之外的 Policy 强制保证。

Verifiability（可验证性） ​

模型说：

done

只能表示 Finish Request。

真正成功应该：

Success Criteria
→ Verifier
→ Evidence
→ SUCCEEDED

P1：Reliability & Progress（可靠性与进展性） ​

Liveness 关注：

重复搜索
重复 Tool Failure
A → B → A → B

Recoverability 在本文只讲 Harness 所需语义：

Action 有 operation_id
State 可识别成功 / 失败
Retry Policy 明确

真正 Checkpoint（检查点）、Resume（恢复执行）和 Durable Runtime（持久执行运行时）的实现，留在《Agent Runtime 与持久执行》中深入。

P2：Efficiency & Economics（效率与经济性） ​

Agent 的探索必须受：

Turns
Wall Time
Tokens
Cost
Tool Calls
Subagents

约束。

最终原则：

先保证 Correctness / Safety，再保证 Reliability，最后优化 Cost / Latency。

不能为了少跑两轮，牺牲 Verification 或 Permission。

Progress Detection 怎样判断任务真的前进 ​

可以定义：

State Delta
Artifact Delta
Observation Novelty
Plan Completion
Verification Score

如果连续 N 轮没有有效变化：

No-progress Loop

但 Progress Detection 不能只看“有没有新 Tool Call”。

例如：

Turn 1: search foo
Turn 2: search foo with another keyword
Turn 3: search foo in another directory

表面上每轮都有 Action，实际上可能没有增加有效信息。

更稳妥的做法是组合多个信号：

Progress Score
=
State Delta
+ New Evidence
+ Artifact Delta
+ Plan Completion Delta
+ Verification Improvement
- Repeated Failure Penalty

实际工程不一定真的计算一个统一数值，但应该至少保留这些可观测信号。

还要避免两个误判：

False Positive（假进展）

不断产生新日志、新搜索结果，但任务没有更接近成功。

False Negative（假停滞）

某些长执行步骤几轮内没有明显 State Delta，但实际上正在进行必要工作。

因此更推荐：

hard budget
+
repetition fingerprint
+
semantic progress signal
+
domain-specific verifier

联合判断。

处理：

REPLAN
SWITCH_TOOL
ASK_USER
ESCALATE
STOP

3.3 并行和常见 Loop 形态怎样治理 ​

不是所有 Tool 都适合并行。

Read-only independent
→ 可以并行

Write same resource
→ 不应直接并行

Independent workspaces
→ 可以并行

Side-effect tool
→ operation id / lock / policy

Agent Loop 的几种常见形态 ​

Reactive Tool Loop（反应式工具循环） ​

Context
→ Model
→ Tool
→ Observation
→ Model

Plan–Execute–Replan（规划—执行—重规划） ​

Goal
→ Plan
→ Execute
→ Observe
→ Re-plan

显式 Planning（规划）并不是所有 Agent 都需要。它真正解决的是：当任务无法靠“看到 Observation 后立即决定下一步”稳定推进时，怎样把长期目标拆成可追踪、可更新的中间承诺。

一个生产级 Plan 至少要回答：

Goal
→ 最终要达到什么状态

Work Item / Todo
→ 当前有哪些可独立验证的子任务

Dependency
→ 哪些任务有先后关系

Owner / Executor
→ 谁负责执行

Status
→ Pending / Running / Blocked / Done

Evidence
→ 凭什么把某个 Todo 标记为完成

所以：

Plan 不是一段“模型想法”，而应该是可以被 Runtime / Harness 追踪和修改的 Working State（工作状态）。

什么时候值得显式规划：

• 任务跨多个 Tool / 文件 /系统；
• 存在先后依赖；
• 用户需要先 Review Plan 再执行；
• 任务会暂停、恢复或跨多个 Turn；
• 需要判断“现在有没有真实进展”。

什么时候反而不应该先生成大 Plan：

• 下一步非常明显；
• 环境信息还不足；
• Tool Observation 会快速改变策略；
• 计划成本高于执行成本。

这时 Reactive Loop（反应式循环）更简单。

Re-plan 什么时候发生 ​

Re-plan 不应该每一轮都把整份 Plan 重写。

更合理的触发条件是：

Observation 与预期不一致
Dependency 改变
某个 Todo Blocked
Budget / Deadline 改变
新事实使旧 Plan 失效
Verifier 证明当前路径不能完成 Goal

所以：

好的 Planning 是“稳定 Goal + 可变 Plan”，而不是让模型固守第一次生成的步骤。

Microsoft Agent Framework 2026 已把 Planning / Todo 做成独立 Context Provider：Todo Provider 持久保存可跟踪工作项，Agent Mode Provider 区分 Plan / Execute Mode，并在每次 Run 前重新注入未完成 Todo；这说明 Planning 正在从 Prompt 技巧变成一等运行状态。[^ms-planning-todos]

OpenAI Agents SDK 则没有强制统一 Planner Primitive，而是明确允许两种编排：让 LLM 自主 Plan / Reason / Decide，或者由代码显式决定 Agent 流程。这个差异说明 Planning 的核心不是“有没有 Planner Agent”，而是谁拥有控制流和计划状态。[^openai-agent-orchestration]

Workflow-embedded Agent Loop（嵌入工作流的 Agent Loop） ​

Deterministic Step
→ Agent Loop
→ Deterministic Step

Nested / Multi-Agent Loop（嵌套 / 多智能体循环） ​

Main Agent Loop
→ Spawn Subagent
   → Subagent Loop
→ Result
→ Main Agent Loop

这里仅定义边界；完整 Multi-Agent 机制由《Multi-Agent 与工作流编排》展开。

四、为什么 Agent Loop 会演进出 Harness ​

4.1 Harness 为什么会自然长出来 ​

Harness 的定义 ​

在讨论为什么出现 Harness 之前，先把概念定义清楚。

本文采用的工程定义：

Harness 是围绕 Agent Loop 构建的一组工程机制，用来决定模型看到什么、暴露哪些能力，请求并消费 Policy Service 的授权决策、在模型外强制执行门禁，控制循环、验证结果，以及扩展和观测系统。

一句话：

Loop 负责反馈运行，Harness 负责把反馈运行变成生产系统。

为什么 Minimal Loop 会自然演进出 Harness ​

定义清楚以后，再看它为什么会自然出现。

最小 Loop 在 Demo 中可以很简单：

while True:
    response = model(messages, tools)
    ...

进入生产后逐渐出现：

Context Management
Tool Registry
Capability Routing
Permission
Budget
Failure Handling
Verification
Trace
Extension
Skill
Subagent

这些问题不断在不同 Agent 中重复出现。

因此才形成：

Agent Harness（Agent 执行外壳）

为什么行业对 Harness 边界没有完全统一 ​

需要区分：

Product Boundary（产品打包边界）

厂商产品把哪些能力一起交付。

Logical Architecture Boundary（逻辑架构边界） ​

企业为了长期演进如何划分职责。

例如某产品可能把：

Tools
Context
Execution Environment

都称为 Harness 的一部分。

企业逻辑架构仍然可以拆：

Harness
Runtime
Execution

这不矛盾。

Harness 与 Framework / SDK 有什么区别 ​

实用但非绝对的理解：

Framework / SDK
→ 开发者如何定义、编排 Agent

Harness
→ Agent 真正运行任务时周围的工程能力

一个项目可能同时具备两种属性。

不要为了贴唯一标签而牺牲真实结构。

4.2 Harness 需要统一哪些生产机制 ​

完整 Pipeline ​

完整 Pipeline（处理链）就是将前文的反馈循环落到稳定契约上。它有三个不变式：模型只提出动作，执行前必须经过模型之外的控制边界；原始执行结果必须转成可对账的 Observation；模型请求结束后必须由 Verification 决定是否真正成功。Policy（策略）、Budget 和 Cancellation 贯穿执行链，Trace（追踪）、Hook（钩子）和 Plugin（插件）则负责观测与扩展，它们不应改变上述三个不变式。

核心机制 ​

真正企业级的实现重点，不是“有没有 Context、Tool、Permission 这些模块”，而是：

它们之间有没有稳定 Contract（契约）、清晰生命周期和可观测的失败语义。

推荐至少明确：

TaskContract
ContextContract
CapabilityContract
ActionContract
ObservationContract
VerificationContract
TraceEventContract

这样 Model、Runtime、Executor、Domain Extension 才可以独立替换。

Context：模型这一轮看到什么 ​

本篇只定义 Harness 应承担的上下文接口边界，不深入《Agent 上下文工程》中的选择、压缩与组装算法。

Harness 至少需要完成：

Collect
→ Filter
→ Select
→ Transform
→ Budget
→ Assemble

输入可能来自：

Task
Run State
Recent History
Files
Knowledge
Memory
Skills
Observations

输出应该是：

当前 Turn 做决策真正需要的信息投影。

关键设计原则：

State ≠ Context
Context 越多 ≠ 决策越好
安全状态不能只存在于 Context

Capability：模型这一轮可以做什么 ​

Capability Registry（能力注册表）和 Model-visible Capabilities（模型可见能力）必须分离。

完整过程：

Global Registry
→ Environment Availability
→ Identity Filter
→ Policy Filter
→ Task / Phase Routing
→ Model-visible Capabilities

一个成熟 Capability 至少应该描述：

interface Capability {
  name: string;
  inputSchema: Schema;
  outputSchema?: Schema;

  riskLevel: "low" | "medium" | "high";
  sideEffect: "none" | "local" | "external";
  idempotent: boolean;

  timeoutMs?: number;
  requiredIdentity?: string[];
  approvalPolicy?: string;
  executor: string;
}

这样 Tool 不再只是：

name + description + JSON schema

而成为一个可以治理的执行能力。

Tool / Capability Lifecycle（工具 / 能力生命周期） ​

生产 Tool 的完整生命周期应该至少考虑：

Discover
→ Filter
→ Expose
→ Select
→ Validate Arguments
→ Authorize
→ Approve（必要时）
→ Execute
→ Validate Result
→ Normalize Observation
→ Persist Evidence
→ Feed Back to Loop

这条链在 Tool 数量很少时可以全部静态配置；一旦能力数量从几十个增长到几百甚至几千个，Discover / Filter / Expose 就不能再被当成“初始化时把所有 Tool 塞给模型”。

Tool 规模上来以后，为什么必须按需发现 ​

Tool Explosion（工具膨胀）有五个不同 Failure：

1. Schema Cost（结构成本）：每个 Tool 的 Name / Description / Input Schema 都占 Context；
2. Selection Confusion（选择混淆）：相似工具越多，模型越容易选错；
3. Parameter Error（参数错误）：工具描述相近、参数语义模糊时，模型可能选对 Tool 却传错参数；
4. Permission Surface（权限暴露面）：模型看见的高风险能力越多，误调用和攻击面越大；
5. Result Pollution（结果污染）：批量 Tool Call 的中间结果会继续挤占 Context。

因此成熟系统通常分成五层：

Global Capability Registry
→ Namespace / Capability Group
→ Candidate Search
→ Identity / Policy / Phase Filter
→ Model-visible Tool Set

不是所有层都必须由 LLM 完成。

• **Namespace（命名空间）**先把能力按 CRM / Billing / Git / Data 等稳定边界分组；
• **Tool Search（工具搜索）**只把当前任务相关 Tool 的完整 Schema 延迟加载；
• **Dynamic Filter（动态过滤）**根据当前 Agent、User、Environment、Phase 和 Policy 决定 Tool 是否可见；
• **Programmatic Tool Calling（编程式工具调用）**适合大量确定性循环、条件分支和中间数据处理，避免每个小步骤都重新进入 Model Context；
• **Tool Result Contract（工具结果契约）**负责过滤、分页、截断和结构化返回，只把 Decision-relevant Result（决策相关结果）送回模型。

这不是单纯 Token 优化，而是在控制模型的 Action Space（动作空间）。

Tool 越多，系统越应该把“能力拥有权”和“模型可见权”分开。

Tool Contract 为什么必须声明副作用语义 ​

Tool Schema 只描述“参数长什么样”还不够。生产系统还需要知道：这个 Tool 调用失败 / 超时 / 重试时，现实世界会发生什么。

至少应该把 Tool 分成几类：

因此 Tool Contract 最好显式声明：

side_effect_class
idempotency_strategy
timeout_semantics
retryable_errors
operation_id_support
reconcile_method
compensation_capability
approval_requirement

这里最容易犯的错误是把：

Tool Timeout

直接解释成：

Tool Failed
→ Retry

真实情况可能是：

请求超时
但远端已经成功产生副作用

这时正确动作不是立即 Retry，而是先 Reconcile（对账）。

所以：

Rollback（回滚）不是所有 Tool 的通用能力。对不可逆或跨系统副作用，企业级保障通常是 Idempotency + Operation Ledger + Reconciliation + Compensation，而不是幻想存在数据库式事务回滚。

具体的 Crash Point（崩溃点）、Operation Ledger（动作账本）、Exactly-once Boundary（精确一次语义边界）和 Saga / Compensation（长事务 / 补偿）机制统一由《Agent Runtime 与持久执行》展开；本篇只要求 Harness 在 Tool Metadata（工具元数据）和执行决策中保留这些语义。

每一步都有不同 Failure Mode：

Select 错
→ Capability Routing 问题

Validate 失败
→ Schema / Model Output 问题

Authorize 失败
→ Permission 问题

Execute 失败
→ Execution 问题

Normalize 错
→ Observation 问题

这也是为什么企业 Debug 不能只看“Tool 调用失败”。

Permission、Guardrail 与 Verification 要分清 ​

这三个概念经常被混用。

Permission / Policy（权限 / 策略）

回答：

这个主体是否被允许执行这个 Action？

Subject
× Resource
× Action
× Environment
× Risk

结果通常是：

ALLOW
ASK
DENY

这个决策链需要明确 Owner：Policy Owner（策略责任人）定义身份、资源、动作和风险规则；Policy Service（策略服务）基于已版本化的规则作出 ALLOW / ASK / DENY 决策，并在允许时签发与主体、动作、资源、环境和有效期绑定的授权票据；Harness 在模型之外编排这次调用并强制执行门禁；Execution 只消费未过期且与当前动作匹配的授权票据。Harness 可以拒绝缺少决策或票据的请求，但不能自行成为业务权限的事实源。

Guardrail（护栏）

回答：

输入、输出或中间结果是否违反规则或格式约束？

例如：

PII detection（个人可识别信息检测）
unsafe content
schema validation
business rule validation

Verification（验证）

回答：

任务目标是否已经真正达成？

例如：

测试是否通过
订单是否真的创建
指标是否真的恢复

所以：

Permission
≠ Guardrail
≠ Verification

三者可以协同，但语义不同。

Loop Control：Agent 是否应该继续 ​

Loop Control 至少综合：

Termination Signal
Budget
Retry Policy
Progress
Failure Fingerprint
Verification Feedback
User Cancel
Human Approval State

它不只是：

max_turns

成熟实现应该能够产生：

CONTINUE
RETRY
REPLAN
ASK_USER
REQUEST_APPROVAL
FINISH
FAIL
CANCEL

这些结果不是对一组指标做简单排序。每个状态只允许部分决策，并且每个决策都需要可追溯的触发证据：

阈值的产生和防振荡机制已在“Retry 与 Idempotency”中给出；这里的状态映射负责将阈值转换成明确决策，不应再引入另一套隐式 Prompt 规则。

Verification：成功语义由谁定义 ​

Harness 不应该硬编码所有领域的“成功”。

更合理的是提供：

Verification Hook / Contract

由 Domain Extension 定义：

Coding
→ tests / build / lint

Data
→ query / semantic / freshness

Browser
→ page state / created object

Ops
→ service health / audit evidence

Harness 负责：

何时触发
如何收集 Evidence
失败如何反馈回 Loop
结果如何写入 Run State

Output Contract：最终输出为什么也需要契约 ​

Tool Argument 有 Schema，并不意味着 Agent 最终输出就天然可靠。

生产系统通常还需要明确：

Final Output Type
Required Fields
Citation / Evidence Requirement
Business Validation
Refusal / Escalation Semantics

Structured Output（结构化输出）解决的是输出形状可解析；Verification / Guardrail 解决的是输出内容是否真的正确、允许和可信。两者不能混为一谈。

例如：

{
  "decision": "approve",
  "risk_level": "low",
  "evidence_ids": [...]
}

即使完全符合 JSON Schema，也可能因为 Evidence 错误而做出错误审批。

因此完整链路应该是：

Model Output
→ Schema Validation
→ Business / Policy Validation
→ Verification
→ Final Result

OpenAI Agents SDK 当前把 output_type 作为 Agent 一等配置，并用 JSON Schema / Pydantic 等做结构化输出和本地解析验证；这类机制适合把 Agent 结果交给下游程序，但仍然不能替代业务 Verification。[^openai-structured-output]

Trace、Hook 与 Plugin：横向扩展能力 ​

Trace（调用链）

回答：

发生了什么？

最少覆盖：

Model Call
Action Proposal
Policy Decision
Execution
Observation
Verification
State Transition

Hook（生命周期钩子）

回答：

在某个生命周期节点能否插入逻辑？

例如：

before_model
after_model
before_action
after_action
before_verify
on_finish

Plugin / Extension（插件 / 扩展）

回答：

如何把一组 Tool、Hook、Service、Skill 或 UI 能力打包成可安装、可版本化的扩展？

因此：

Hook
= extension point

Plugin
= packaged extension

不是同义词。

**Middleware（中间件）**又是另一类抽象。

它解决的是：

哪些横切逻辑应该按固定顺序包在每一次 Agent / Tool 执行路径外面，而不是散落进每个业务 Tool。

典型 Middleware：

Auth / Policy
Rate Limit
Guardrail
Telemetry
Redaction
Retry Classification
Exception Handling

所以三者边界是：

Hook
→ 某一个生命周期点的回调

Middleware
→ 按顺序包围执行链的横切控制

Plugin
→ 把 Tool / Hook / Middleware / Skill 等打包成可安装扩展

Microsoft Agent Framework 已经把 Logging、Guardrail、Exception Handling、Runtime Context 等作为 Middleware 的典型职责；OpenAI Agents SDK 则把 Input / Output / Tool Guardrail 放在不同执行边界，尤其 Tool Guardrail 可以在真正调用 Tool 前后阻断或改写结果。[^ms-middleware][^openai-guardrails]

最小 Harness Interface ​

下面这个接口是参考设计，不是某个框架的官方 API。目的不是要求所有团队照抄，而是把 Harness 的职责转换成可讨论、可替换的工程边界。

interface HarnessCore {
  run(task: TaskContract): Promise<RunResult>;

  buildContext(
    state: RunState
  ): Promise<ModelContext>;

  resolveCapabilities(
    state: RunState,
    identity: Identity
  ): Promise<Capability[]>;

  requestAuthorization(
    action: AgentAction,
    state: RunState,
    identity: Identity
  ): Promise<AuthorizationTicket>;

  normalizeObservation(
    result: RawExecutionResult,
    state: RunState
  ): Promise<Observation>;

  verify(
    state: RunState
  ): Promise<VerificationResult>;

  control(
    state: RunState
  ): Promise<LoopDecision>;
}

interface ExecutionPort {
  execute(
    action: AgentAction,
    authorization: AuthorizationTicket,
    environment: ExecutionEnvironment
  ): Promise<RawExecutionResult>;
}

interface PolicyPort {
  decide(
    action: AgentAction,
    state: RunState,
    identity: Identity
  ): Promise<PolicyDecision>;
}

PolicyPort 由 Policy Service 实现，业务规则的 Owner 不在 Harness Core。requestAuthorization 表示 Harness 编排授权请求、处理审批并强制门禁，不表示 Harness 自行解释业务权限。ExecutionPort 要求授权票据，是为了防止调用方绕过 Harness 直接执行高风险动作。

这里特意把：

Harness Core

和：

ExecutionPort

拆开。

原因是：

Harness 编排“应该请求什么动作、何时请求授权、结果如何解释”；Policy Service 决定动作是否被允许；Executor 校验授权票据并负责“动作到底如何在 Shell / Browser / VM / Sandbox 中发生”。

对应关系：

run
→ Loop orchestration

buildContext
→ Context boundary

resolveCapabilities
→ Capability exposure

requestAuthorization
→ Policy Service decision / authorization ticket

ExecutionPort.execute
→ Execution boundary

normalizeObservation
→ Observation semantics

verify
→ Success semantics

control
→ Loop semantics

这个拆法也更符合后文：

Harness
≠
Execution

的逻辑边界。

4.3 Harness 最常见的反模式是什么 ​

反模式一：所有 Tool 全量暴露 ​

Registry = Model-visible Tools

问题：

• Context 膨胀；
• Tool 选择错误上升；
• 相似 Tool 混淆；
• 权限面扩大。

正确方向：

Registry
→ Capability Routing
→ Policy
→ Visible Tools

反模式二：用 Prompt 代替 Permission ​

System Prompt:
“不要删除生产数据库”

这不是安全边界。

真正的权限必须存在于模型之外：

Action Proposal
→ Policy Engine
→ Allow / Ask / Deny

反模式三：model_done == success ​

模型说完成，只代表：

模型提出 Finish Request。

真正成功应该由 Verification Contract 决定。

反模式四：State 直接等于 Context ​

会导致：

• 内部状态泄漏给模型；
• Context 无法压缩；
• Runtime 和 Prompt 强耦合；
• Resume 难以重建不同模型需要的 Context。

反模式五：所有能力都塞进 Harness Core ​

结果是：

Core
→ Memory
→ Browser
→ Sandbox
→ Workflow
→ Eval
→ Multi-Agent
→ Everything

最终 Core 成为平台瓶颈。

反模式六：所有任务默认 Multi-Agent ​

Subagent 是 Harness 能力，不是默认目标。

如果单 Agent 能以更低成本稳定完成：

不应该为了“架构高级”强行拆 Multi-Agent。

反模式七：所有失败都 Retry ​

必须先区分 Transient Failure（短暂性失败）、Deterministic Failure（确定性失败）、Permission Failure（权限失败）、No-progress（无进展）和 Side-effect Uncertainty（副作用状态不确定）。其中最危险的不是返回了错误，而是请求超时后不知道现实动作是否已发生。

带副作用的动作进入 Retry 前，Harness 必须先通过 operation_id、幂等键或业务查询接口读取真实状态：

查询真实执行状态
├─ 明确未执行：在 Retry Policy 允许时重试
├─ 明确已执行：复用真实结果，不重复产生副作用
├─ 幂等键已命中：读取原动作结果并继续
└─ 状态不明且动作不可幂等：停止自动化，进入对账、补偿或人工处理

该分支的验收证据不是“Retry 没有报错”，而是同一 operation_id 只对应一份可对账的业务结果，Trace 能复原每次状态查询和重试决策，最终 Verifier 用外部状态证明任务成功或明确转入补偿。确定性参数错误应 Re-plan，权限失败应重新请求授权或终止，无进展应切换策略或人工接管，都不应只做机械重试。

五、主流 Harness 怎样设计 ​

5.1 主流实现怎样验证 Harness 机制 ​

先用统一维度比较 ​

统一看这些维度：

Core Thickness（核心层厚度）
Extension Model（扩展模型）
Context（上下文策略）
Tool / Capability（工具 / 能力治理）
Permission（权限控制）
Subagent（子智能体）
Execution（执行环境）
Runtime Boundary（运行时边界）

这八个维度回答的不是“功能多不多”，而是责任放在哪里：Core Thickness 影响升级协调和默认能力，Extension Model 影响组合与版本风险，Context、Capability 和 Permission 共同决定模型当前能看什么、能选什么、最终能做什么，Execution 与 Runtime Boundary 则决定执行环境和持久执行能否独立替换。

先看实现机制，不按产品 Feature 数量比较 ​

在进入具体项目之前，可以先把研究对象映射回本文的 Harness 主线：

这张表的目的不是穷举 Feature，而是让后面的每个项目都回答同一组问题：

Loop 怎么跑？
Context 怎么管？
Capability 怎么暴露？
Permission 怎么控？
Extension 怎么长？
State 怎么保存？
Execution 在哪里？

这样框架研究才不会退化成 README 摘抄。

极简路线：mini-SWE-agent 与 Pi ​

mini-SWE-agent ​

它最值得研究的是：

Agent Loop 到底能有多简单。

当前 v2 官方仍明确强调“100 line AI agent”，并公开说明其核心特点包括 Bash-only、线性消息历史和独立 subprocess.run Action 执行。[^mini-swe]

重要启示：

Agent Intelligence 不等于 Framework Complexity。

更进一步，研究 mini-SWE-agent 的价值在于建立一个“复杂度基线”：

如果百行级 Loop 已经可以完成任务，
那么后来每增加一层抽象，都应该回答：
它解决了什么真实 Failure Mode？

Pi ​

Pi 官方明确定位：

minimal terminal coding harness

核心方向：

Small Core
+
Extensions
+
Skills
+
Prompt Templates
+
Packages

值得研究：

• Extension Lifecycle；
• Skill 按需加载；
• Context / Compaction 可定制；
• Session Tree；
• Core / Extension Boundary。

Pi 的 Extension 已经可以注册 Tool、拦截或修改 Tool Call、注入 Context、自定义 Compaction、监听 Session 生命周期并持久化扩展状态。[^pi-extension]

它的 Compaction 也已经公开到工程细节：超过 Context 阈值后，保留最近一段消息、把更老内容压缩成结构化 Summary，再重建下一轮 Context；Session Tree 还能在切换分支时生成 Branch Summary。[^pi-compaction][^pi-session]

这说明 Thin Core 并不是：

“什么都不做”。

而是：

把扩展性设计成一等能力，让 Core 保持稳定。

Pi 的核心价值不是：

功能少。

而是：

Core 小，但 Extension Contract 强。

插件路线：DeepSeek Harness ​

官方明确：

Everything is a Plugin.

底层 Cordis 使用：

Plugin
Service
ctx
inject
Typed Event
Lifecycle

形成：

Tool
LLM
Session
Storage
Sandbox
Agent Loop
      ↓
Plugin

优势：

• 统一扩展模型；
• 强组合；
• Core 对具体能力解耦。

风险：

• Plugin dependency；
• lifecycle ordering；
• implicit coupling；
• compatibility；
• third-party plugin security。

企业如果采用类似模型，还需要：

dependency graph
version contract
lifecycle trace
security isolation
conflict detection

DeepSeek Harness 的公开架构已经把这种思路落实到很具体的运行模型：ctx.tools、ctx.llm、ctx.agents 都是 Service；插件通过 inject 声明硬依赖，服务消失时依赖插件会自动卸载，服务恢复后重新加载。[^dsh-service]

它的 Agent Loop 甚至明确区分 Turn 与 Step：一个 Step 是一次模型请求及其 Tool Calls；一个 Turn 可以包含多个 Step，并把 turn/*、step/*、tool/* 作为 durable session events（持久会话事件）。[^dsh-architecture]

这非常值得企业平台学习：

Harness 不只是“几个 Hook”，而可以拥有完整、可观察、可恢复的生命周期语义。

产品路线：Claude Code 与 OpenCode ​

Claude Code ​

代表：

Opinionated Production Harness（强默认生产级执行外壳）

Claude Code 官方当前明确把自己描述为 Claude 模型外层的 agentic harness，核心 Agentic Loop 是 Gather Context → Take Action → Verify Results → Repeat；公开能力包括 Tools、Permissions、Skills、Subagents、Context Management、Compaction、Session、Tool Search 等。[^claude-code][^claude-loop]

值得学：

成熟产品什么时候应该替用户做更多默认决策。

从架构角度，Claude Code / Claude Agent SDK 类产品最值得关注的不是 Tool 数量，而是：

Context Management
+ Permission
+ Hooks
+ Verification-oriented workflow
+ Subagent
+ Budget / Loop Control

已经被整合成统一产品体验。

OpenCode ​

代表：

Open / Provider-agnostic Harness（开放、模型提供方无关）

当前明确区分：

Build Agent
Plan Agent
General
Explore
Scout
Compaction Agent

重要启示：

Agent Specialization 可以通过 Tool / Permission / Context Profile 工程化，而不是只靠 Role Prompt。

OpenCode 当前公开的 Build / Plan / General / Explore / Scout 就是很直接的例子：Build 拥有完整工具权限，Plan 默认限制编辑并对 Bash 提问确认，Explore / Scout 更偏只读检索，另有隐藏 Compaction Agent 自动压缩长 Context。[^opencode-agents]

这意味着所谓“多个 Agent”并不一定要先从：

多个不同 Prompt

开始，而可以从：

不同 Capability
+ 不同 Permission
+ 不同 Context Policy

开始。

平台路线：OpenAI Agents SDK 与 Codex ​

OpenAI Agents SDK 当前 Runner 的 Loop 语义已经公开得比较清楚：模型输出 Final Output 时结束；输出 Tool Calls 时执行并再次进入 Loop；输出 Handoff 时切换 Active Agent 后继续；超过 max_turns 则停止。[^openai-runner]

它还区分两种多 Agent 语义：

Handoff
→ 仍然是同一个 top-level Run，只是下一 Turn 换 Agent

Agent.as_tool()
→ 外层 Tool Call 启动一个 Nested Run（嵌套运行）

嵌套 Run 拥有自己的 Turn Loop 和 max_turns。[^openai-sandbox]

这对于理解：

Run
Turn
Nested Loop

是非常好的真实实现案例。

OpenAI Agents SDK 当前 Runner 负责：

model call
tool call
handoff
final output
max turns
session
guardrail

同时 OpenAI 2026 年又持续加入：

Memory
Filesystem
Shell
Skills
Sandbox-aware orchestration

说明：

Framework、Runtime、Harness 在真实产品中可能能力重叠。

Codex 则进一步体现：

Coding Harness
→ Reusable Harness
→ Cloud Agent Infrastructure

OpenAI 在 2026-09-10 发布的 Agents API 当前明确以 Codex harness 为基础运行 Cloud Agent，并允许选择 OpenAI Hosted Sandbox、自有基础设施或 Sandbox Partner。[^openai-agents-api]

最重要的企业启示：

Harness Intelligence 与 Compute / Sandbox 可以解耦。

大型 Tool Surface：主流实现已经从“全量暴露”转向“按需发现” ​

Tool 多到一定规模后，行业实现已经明显收敛。

OpenAI Agents SDK

OpenAI 当前提供 ToolSearchTool：Tool 可以 defer_loading=true，先隐藏完整 Schema，由模型在需要时搜索并加载；官方还推荐把相关 Tool 组织成 Namespace，并支持 MCP Tool 的静态 / 动态过滤。[^openai-tool-search][^openai-mcp-filter]

Anthropic

Anthropic 公开的 Advanced Tool Use 直接把“几十 / 数百 Tool 导致 Context 被 Schema 占满、选错 Tool、参数错误”当成生产问题。它给出的三类能力是：

Tool Search
Programmatic Tool Calling
Tool Use Examples

其中 Tool Search 负责按需加载，Programmatic Tool Calling 负责在代码环境里做循环 / 条件 / 聚合，Tool Use Examples 则补足 JSON Schema 无法表达的正确使用范式。[^anthropic-advanced-tool-use]

Anthropic 对 Tool Design 的另一条生产经验是：不要把每个底层 API Endpoint 都机械包装成 Tool。更高层、任务导向的 Tool 往往更容易被 Agent 正确使用，并且 Tool Result 应主动分页、过滤和截断。[^anthropic-effective-tools]

AWS AgentCore Gateway

AgentCore Gateway 现在支持对大量 Gateway Tool 做 Natural-language Semantic Search（自然语言语义搜索），说明 Tool Discovery 已经开始成为独立平台能力，而不是 Agent Prompt 的附属逻辑。[^aws-tool-semantic-search]

这几条路线共同说明：

Tool Scaling 的最佳实践不是“给模型更多工具”，而是构建 Capability Registry + Search + Filter + Policy + Eval。

5.2 主流路线共同收敛到什么，真正分歧在哪里 ​

比较这些项目时，最容易犯的错误是把它们排成一条“谁更先进”的线。

更合理的方式是看多个独立设计维度：

可以把它理解成一个多维选择空间：

所以问题不应该是：

“哪个 Harness 最先进？”

而应该是：

“我的场景需要在哪些维度上更强默认、更多扩展、更薄 Core 或更强 Execution 解耦？”

这才是架构选择，而不是产品排名。

主流实现共同收敛的机制 ​

跨极简 Harness、Plugin-first、产品型 Coding Harness 和 SDK / Cloud Agent，可以看到几条稳定方向：

1. Loop Core 越来越小而稳定：模型调用、Tool / Handoff、Observation、Stop / Verification 是最小骨架。
2. Capability / Permission / Context Profile 被显式化：专业化不再只靠 Role Prompt。
3. Execution 正在从 Harness 解耦：同一个 Agent Logic 可以落到 Local、Sandbox 或 Cloud Runtime。
4. 长任务需要 Compaction、Progress Detection 和可恢复状态：Harness 开始与 Context / Runtime 接口协作。
5. 生产 Harness 必须有 Policy / Verification / Trace：否则只是 Demo Loop。

真正没有统一答案的地方 ​

行业仍然在这些维度上做不同取舍：

• Core 应该 Thin 还是 Rich；
• Extension 应该靠 Plugin、Hook 还是 SDK Primitive；
• Governance 默认应该多强；
• Multi-Agent / Handoff 应该由 Harness 内建到什么程度；
• Session / Runtime / Execution 应该由 Harness 自己承担多少。

因此企业应该统一的是 Harness Contract 和治理不变量，而不是复制某个产品的完整 Feature 集。

六、企业级 Harness 怎样设计 ​

6.1 企业 Harness 应该统一什么 ​

设计原则 ​

核心原则：

统一稳定不变量，而不是统一所有 Agent 行为。

6.1.1 Harness 为什么会从“几段胶水代码”演进成独立架构层 ​

Harness 不是因为 Agent Framework 越来越复杂才出现，而是因为最小 Loop 进入真实生产后，一批问题开始反复出现：

模型看到什么
→ Context Boundary

模型能做什么
→ Capability Exposure

动作能不能真的执行
→ Permission / Policy

失败以后怎么办
→ Retry / Re-plan / Progress

什么时候算完成
→ Verification

怎么解释这次行为
→ Trace / Version

多个 Agent 是否重复建设
→ Shared Harness

因此更准确的演进链是：

LLM + Tool Calling
→ 能调用外部能力

Agent Loop
→ 能根据环境反馈持续决策

Production Loop
→ 开始面对权限、失败、预算、验证、观测

Harness
→ 把这些重复的生产控制语义收敛成稳定 Contract

Shared Harness
→ 当多个 Domain Agent 重复建设时再平台化

关键结论：

Harness 不是 Agent 的“高级 Feature”，而是非确定性决策进入生产环境后自然出现的控制边界。

6.1.2 Harness 没有消灭复杂度，只是重新分配复杂度 ​

Harness 的价值不是让系统“没有复杂度”，而是把原本散落在 Prompt、业务代码和 Tool Wrapper 中的复杂度，迁移到更适合治理的位置。

所以架构评审不能只问：

“这个 Harness 多了哪些能力？”

还必须问：

“这些能力把复杂度从哪里搬到了哪里？新的复杂度我们是否真的有能力治理？”

6.1.3 Harness 的升级应该由 Trigger 驱动，而不是由 Feature 驱动 ​

和《企业级 Agent 架构全景》保持一致，Harness 演进统一看五类 Trigger（触发信号）：

Failure Trigger
→ 死循环、假完成、Tool 误选、Retry 重复副作用

Scale Trigger
→ Tool / Turn / Agent / Plugin 数量导致简单方案失效

Risk Trigger
→ Production Write、敏感数据、不可逆动作增加

Reuse Trigger
→ 多个 Agent 重复实现 Policy / Trace / Verification

Governance Trigger
→ 多团队、多版本、多租户开始失控

具体规模变化与演进案例统一放在 6.4 Scale Review（规模检查），这里不重复展开。

架构决策统一使用：

Trigger
→ 当前方案为什么开始失效

Decision
→ Harness 增加什么能力

Trade-off
→ 新增什么复杂度

Evidence
→ 用什么任务级指标证明值得

这样可以避免从“想上什么 Feature”倒推需求。

不推荐两个极端：

每个 Agent 自己实现 ​

导致：

• 重复建设；
• 权限不一致；
• Debug 困难；
• Trace 分散。

超级 Harness ​

把：

Memory
Runtime
Sandbox
Browser
Workflow
Multi-Agent
Eval

全部写进 Core。

导致：

• Core 膨胀；
• Domain 被限制；
• 升级风险极高。

Autonomy Budget 怎样限制自主性 ​

Autonomy Budget 是本文用于架构分析的一个视角，不是当前所有 Agent Framework 都采用的统一正式术语。

企业设计 Harness 时，一个非常重要但经常被忽略的问题是：

到底允许模型自主决定多少事情？

自主性不是：

Agent / Not Agent

二元开关，而是可以逐层分配。

例如：

因此可以把 Harness 看成：

Autonomy Budget Manager（自主性预算管理器）

原则是：

高不确定性
→ 可以提高决策自主性

高风险 / 高副作用
→ 应降低执行自主性

这比简单讨论“Agent 自主不自主”更适合企业架构。

Stable Core 应该包含什么 ​

这里的 Stable Core（稳定核心）不是“大家常用的功能集合”，而是不随业务领域变化的控制语义。判断一项能力是否应进入 Core，可以连续追问四个问题：

1. 它是否在 Data、Coding、Browser 和 Ops Agent 中具有相同语义？
2. 它是否必须位于模型之外，才能形成强制保证？
3. 它的版本变化是否需要全局审计和回滚？
4. 它是否可以只定义契约，而把领域实现留在扩展层？

只有大多数答案为“是”时，才适合进入 Stable Core。按这个标准，核心通常只保留 Run / Turn 状态语义、Tool Contract（工具契约）、Context Interface（上下文接口）、Policy Hook（策略扩展点）、Budget、Cancellation、Verification Hook（验证扩展点）和 Trace Event（追踪事件）。

这些能力共享的是“语义和生命周期”，不是统一的业务规则。例如 Core 规定每次结束都必须有 Verification Result（验证结果），但不规定“SQL 口径正确”或“代码测试通过”的具体判定逻辑。

Standard Capabilities 应该共享什么 ​

平台可以为 Filesystem（文件系统）、Shell（命令执行）、Planning（规划）、Todo（任务清单）、Compaction（上下文压缩）、Skill（技能）、Subagent（子智能体）和 Approval（审批）提供默认实现，但它们应当作为 Standard Capabilities（标准能力）可替换、可禁用、可按 Agent Profile（智能体配置档）组合，而不是写死在 Core 内部。

区分 Core 和 Standard Capability 的关键测试是“拔掉实现后，Loop 的控制语义是否仍然成立”。例如替换 Shell Provider（命令执行提供方）不应改变 Action Contract、Policy Decision 和 Observation Contract；禁用 Subagent 也不应让单 Agent Loop 无法运行。如果做不到，说明扩展实现已经反向污染核心契约。

Domain Extensions 为什么必须留给业务 ​

领域能力不能进入 Core，不是因为它们不重要，而是因为“什么算正确”由业务语义决定。

因此复用边界应是：平台统一“何时调用、如何治理、如何留证”，领域负责“调用什么、什么算对、失败后如何补救”。

6.2 Harness、Runtime 与 Execution 怎样分工 ​

先用职责矩阵一次看清：

一句话：

Harness
→ 决定怎么工作

Runtime
→ 保证这个 Run 能长期可靠存在

Execution
→ 真正改变外部世界

下面再分别展开。

Harness（执行外壳） ​

回答：

Agent 怎么干活。

Context
Tool
Permission
Loop Control
Verification

Runtime（运行时） ​

回答：

Run 怎么可靠地活着。

State Persistence
Checkpoint
Retry / Resume
Scheduling
Concurrency
Durability

这里需要特别区分“状态语义”和“状态耐久性”：

Harness / Loop
→ 定义和消费 Run State 的逻辑语义
   例如当前 Observation、Budget、Verification 状态

Runtime
→ 负责这些状态如何持久化、恢复、并发控制和长期运行

因此不是：

Harness 有 State
vs
Runtime 也有 State

两个相互冲突的定义，而是：

Harness 关心 State 表达什么；Runtime 关心 State 如何可靠存在。

Execution（执行） ​

回答：

动作在哪里发生。

Sandbox
Shell
Browser
VM
Container

这里只建立边界；详细 Runtime 与 Execution 分别留给《Agent Runtime 与持久执行》和《Agent 安全执行与结果验证》。

6.3 企业 Harness 怎样落地并复用 ​

Enterprise Reference Architecture（企业参考架构） ​

贯穿案例：Coding Agent ​

用户：

修复登录接口偶发 401，不修改数据库 Schema，确保测试通过。

Task Contract（任务契约） ​

Goal:
修复 401

Constraints:
不改 schema
不操作 production

Success:
tests pass
build success
lint clean

Context（上下文） ​

Task
Repo Instructions
Relevant Files
Current Diff
Latest Failure

Capability（能力） ​

只暴露：

search_code
read_file
edit_file
run_test
run_build
git_diff

Decision（决策） ​

先搜索 token refresh

Coding Agent 的 Permission ​

read
→ allow

edit sandbox
→ allow

push main
→ approval

Coding Agent 的 Execution（真实执行）

真实 Shell / File 环境执行。

Observation（观察结果） ​

expected token expiry > now
actual token already expired

下一轮决策

模型修改策略。

Finish（完成） ​

Agent 主动跑测试。

Harness 最后强制：

tests
build
lint
scope check

全部通过：

verified_done = true

这一个案例可以把整篇核心概念串起来。

跨领域案例：同一个 Harness Core 如何复用 ​

Data Agent：从“生成 SQL”升级成“可验证取数” ​

Task Contract：

Goal:
回答“华东区上月 GMV 同比”

Success:
- 使用正确指标口径
- SQL 可执行
- 数据新鲜度满足要求
- 结果附 Evidence

Domain Context：

Semantic Layer
Metric Definition
Table Metadata
Business Glossary

Action：

search_metric
generate_sql
execute_sql
python_analysis

Verification：

SQL execution success
metric lineage correct
time range correct
row count sane

Shared Harness Core 仍然是：

Run
Context Interface
Capability Routing
Policy
Budget
Verification Hook
Trace

Browser Agent：为什么 Observation 更重要 ​

Task：

在后台系统中创建一个测试工单。

Action：

Navigate
Click
Type
Submit

这里最危险的错误是：

Agent 以为点击了
≠
页面真的进入目标状态

所以 Observation 应该来自真实 UI State，例如：

current URL
visible element
page text
screenshot / accessibility tree

Verification 则是：

ticket id appeared
status = created

这说明 Browser Agent 的核心差异不在 Loop，而在：

Action Space 与 Observation Space。

Ops Agent：为什么 Permission 与 Verification 更重要 ​

Task：

诊断某服务 P99（99% 请求不超过的延迟分位值）异常。

允许：

query metrics
read logs
read runbook

高风险 Action：

restart pod
scale service
change config

应该经过：

Policy Service 决策
→ 必要时人工审批
→ 签发授权票据
→ Execution 校验票据后执行

Verification：

P99 recovered
error rate normal
change recorded

这说明：

同一个 Harness Core，在不同 Domain 中最需要替换的是 Context、Capability 和 Verification，而不是重新发明整个 Loop。

6.4 什么时候应该把 Harness 平台化 ​

Scale Review（规模评审） ​

小规模 Demo 和企业平台的最大区别，不只是“请求更多”，而是很多简单设计会失效。

下表的 Tool 数和 Turn 数是用于说明数量级变化的示意场景，不是所有企业都应照抄的平台化阈值。真正的触发条件是全量暴露、无进展循环、环境调度或多团队协作已经产生可复现失效。

因此：

Scale 不是把原系统放大，而是会让原来隐含的边界变成显式平台能力。

例如 Tool：

20 tools
→ Model 可以直接选

200 tools
→ Tool Context 变大
→ 选择错误增加
→ 权限面扩大
→ 必须 Routing / Search

再例如长任务：

5 turns
→ messages.append() 足够

100+ turns
→ Context Growth
→ No-progress / Repetition
→ Budget / Progress / Compaction 成为一等能力

这也是企业 Harness 不应该从“最终大平台蓝图”倒推，而应该从真实 Scale Failure 逐步演进的原因。

企业演进路线 ​

演进不应该只是“按顺序开发功能”，而应该由可观测的失效信号触发，每一阶段都交付可验收的契约：

这条路线的核心门禁是：没有可复现的失效证据、没有跨场景稳定语义、没有可衡量的复用收益时，不进入下一阶段。这样才能避免先造超级平台，再寻找业务场景。

七、生产问题如何治理 ​

7.1 先建立失败分类和 Debug 路径 ​

Failure Taxonomy（失败分类） ​

真正有价值的不是“失败分类”这组英文名称，而是让每类 Failure（失败）都映射到不同 Evidence（证据）和修复动作。下表是排查入口，不是看到症状后只改一个参数的修复菜单：

核心价值：

避免把所有 End-to-end Failure 都归因于 LLM。

Debug 方法 ​

生产 Debug 推荐沿 Agent Loop 的真实数据流向前排查，而不是从模型开始猜。

读图顺序是从左到右：只有前一层的输入和证据都与契约一致，才继续检查后一层。当任务、上下文、能力、策略、执行、Observation 和 Verification 都能自证时，再将剩余失败归因给 Model 或 Planning。

为什么最后才看 Model？

因为很多“模型错误”实际上是：

没给对信息
没给对工具
工具执行失败
结果被错误总结
Verifier 定义错

如果这些没有排除，直接换更强模型只能暂时掩盖系统问题。

Debug 时最好能够从 Trace 中恢复一个完整 Turn：

Task Snapshot
Context Snapshot
Model Output
Action Proposal
Policy Decision
Raw Execution Result
Observation
State Delta
Verification Result

这样才能真正回答：

这次失败是在哪个状态转换上发生的？

7.2 哪些典型故障会暴露 Harness 缺口 ​

下面的场景用于架构推演和故障注入设计，不冒充任何企业未公开的真实事故。

Agent 假完成 ​

症状

Agent: fixed
CI: failed

根因

系统把：

model_done

直接映射成：

run.status = SUCCEEDED

模型的 Finish 只是一个 Decision，不是外部事实。

看似合理但错误的修复

在 Prompt 里加：

“结束前一定要认真测试。”

这只能提高概率，不能建立成功语义。

正确修复

Finish Request
→ Domain Verification
→ Evidence
→ Pass?
   ├─ Yes → SUCCEEDED
   └─ No  → Observation → Loop

企业结论

Completion 必须是系统状态，不应该是模型的一句话。

Tool 越多，效果越差 ​

症状

Tool 从 20 个增长到 200 个后：

• Tool Selection Error 上升；
• Context 变长；
• 延迟上升；
• 相似 Tool 经常混淆；
• 高风险能力暴露面扩大。

根因

Registry == Model-visible Tools

把“平台拥有的所有能力”错误等同于“模型当前应该看到的能力”。

错误修复

只靠给 Tool Description 写得更长。

Description 可以改善选择，但不能解决暴露面、权限和 Context Cost。

正确修复

Registry
→ Environment Availability
→ Identity
→ Policy
→ Task / Phase Routing
→ Ranking
→ Model-visible Capabilities

企业结论

Capability Scale 越大，越需要 Discovery / Routing，而不是全量暴露。

Plugin 升级导致全局回归 ​

症状

一个共享 Plugin 更新后，多个 Agent 同时出现：

• Tool schema 不兼容；
• Hook 顺序变化；
• Context 注入重复；
• Completion 行为改变。

根因

agent always loads latest plugin

Plugin 被当作普通业务代码，而不是平台依赖。

正确修复

semantic version
→ compatibility matrix
→ version pin
→ contract test
→ historical replay
→ shadow
→ canary
→ rollout / rollback

如果是 Plugin-first Harness，还应额外关注：

• dependency graph；
• lifecycle order；
• service conflict；
• supply-chain security。

企业结论

Plugin 一旦被多个 Agent 复用，就必须按基础设施治理。

所有失败都自动 Retry ​

症状：

create_order()
→ timeout
→ retry
→ 创建两个订单

根因：

把“请求超时”误判成“执行失败”。

修复：

operation_id
idempotency key
execution status lookup
retry policy

结论：

Retry 必须和 Side Effect / Idempotency 一起设计。

Context 压缩后权限语义丢失 ​

症状：

Agent 原本处于只读模式
→ Context Compaction
→ 后续错误执行写操作

这类问题说明：

安全策略不能只存在于 Prompt / Context 中。

Permission 必须是模型之外的系统状态，并在每次 Action 前重新检查。

7.3 Loop Control 怎样进入生产治理 ​

检测：

State Delta
Artifact Delta
Observation Novelty
Plan Completion
Verification Delta

连续无变化：

REPLAN
ASK_USER
SWITCH_TOOL
ESCALATE
STOP

指标体系

指标不能全部同权。

Tool / Capability 还要单独观察一组“动作选择质量”指标：

Tool Eval 不能只测“Tool 能不能调用成功”，还要测“模型是否在正确时机、用正确参数、调用正确能力”。

指标名称本身不会自动形成治理。企业落地时必须先固定样本单位、分母和归因边界，否则不同团队会用同一个指标表达不同事实。例如：

Verified Task Success Rate
= 通过任务成功契约验证的 Run 数 / 可评估 Run 总数

No-progress Loop Rate
= 触发无进展阈值的 Run 数 / 启动过 Loop 的 Run 总数

Retry Recovery Rate
= 重试后恢复且最终验证成功的失败数 / 执行过重试的可恢复失败总数

统计时还需要按任务类型、风险等级、模型版本、Harness 版本和 Tool 版本切分。只看全局平均值，可能用大量简单任务掩盖高风险任务的回归。

下面的 P0、P1、P2 只表示 Harness 质量指标的观测优先级，不表示投资阶段或系统成熟度。

P0 指标：Outcome / Correctness（结果与正确性） ​

这层先回答：

任务到底有没有真的做对？

P1 指标：Reliability / Control（可靠性与控制） ​

这层回答：

系统为什么做不对 / 不稳定？

P2 指标：Efficiency / Economics（效率与经济性） ​

这层回答：

即使做对了，是否足够快、足够便宜？

北极星：

在安全、成本和延迟约束下最大化 Verified Success。

Agent Cost Model（智能体成本模型） ​

Agent 的成本不能只看单次 Model Token。

一个 Run 的综合成本可以拆成：

Total Run Cost
=
Model Cost
+ Tool / API Cost
+ Compute / Sandbox Cost
+ Storage / Artifact Cost
+ Retry Waste
+ Human Intervention Cost

更重要的是：

Cost per Successful Run
=
Total Cost of All Runs
/
Verified Successful Runs

因为一个“单次便宜但成功率很低”的 Harness，整体可能更贵。

Turn 数会放大成本 ​

假设：

每 Turn Model Cost = C
平均 Turns = N

粗略：

Model Cost ≈ C × N

如果 No-progress Loop 把：

10 Turns
→ 40 Turns

成本会直接倍增，同时延迟也增加。

所以 Progress Detection 不只是可靠性能力，也是 Cost Control。

Multi-Agent 会出现 Context Duplication Cost ​

如果 5 个 Subagent 都继承完整 Context：

Context Cost
≈ Parent Context × 5

再加上各自 Loop：

Total Cost
≈ Σ(Subagent Turns × Context)

因此 Subagent Isolation / Minimal Context Pack 同时是架构和经济问题。

Tool / Execution Cost 也要进入预算 ​

例如：

Browser Session
Cloud Sandbox
SQL Warehouse
External Search API
GPU Tool

可能比模型 Token 更贵。

因此 Harness Budget 可以同时限制：

max_model_cost
max_tool_cost
max_execution_minutes
max_subagents

而不是只设：

max_turns

Human Intervention 是隐藏成本 ​

一个 Agent：

成功率 95%
但 60% 任务都需要人工确认

和：

成功率 93%
只有 5% 需要人工

企业总成本可能完全不同。

所以 Economics Review 要把 Human Intervention Rate 纳入。

7.4 怎样测试、评测和发布 Harness 变更 ​

生产 Agent 至少要区分三个完全不同的问题：

Testing 应尽可能不依赖真实模型。

例如 Harness 自己拥有的这些行为：

Tool dispatch
Handoff routing
Guardrail tripwire
Retry classification
Session append / resume
Structured output parsing
Sandbox capability wiring

如果能够用 Scripted / Fake Model 确定性触发，就应该进入普通测试，而不是每次都调用昂贵且非确定的模型做 Eval。

OpenAI Agents SDK 当前已经提供 provider-neutral 的 deterministic testing utilities，用内存中的 Scripted Model 测 Tool、Handoff、Guardrail、Retry、Session、Sandbox 等 SDK / Application-owned behavior，同时明确把外部模型、网络协议和 Sandbox Provider 行为留给真实 Integration Environment。[^openai-agent-testing]

Verification：

单次 Run 是否真的完成。

Evaluation：

一个 Agent / Harness 版本在一批任务上整体表现怎样。

Coding：

Verification
→ 当前 tests pass

Evaluation
→ 1000 个历史任务总体成功率

Model 与 Harness 怎样做 A/B（对照实验） ​

建议二维实验：

这样分别看：

固定 Harness 换 Model
→ Model Delta

固定 Model 换 Harness
→ Harness Delta

同时记录：

model_version
harness_version
prompt_version
tool_version
skill_version

Harness Ablation / Counterfactual Eval（执行外壳消融与反事实评测） ​

只看：

Harness B 成功率 > Harness A

还不知道：

到底哪个机制产生了收益？

所以可以增加 Causal Eval。

Ablation（消融） ​

逐个关闭能力：

Full Harness
vs
No Verification
vs
No Capability Routing
vs
No Progress Detection
vs
No Compaction

比较：

Verified Success
Cost
Latency
Failure Mix

如果关闭某能力几乎没有变化：

可能这个能力没有真实收益，或者测试集没有覆盖它的价值场景。

Counterfactual（反事实） ​

主动构造错误条件：

Tool 数量从 20 → 200
Permission Policy 错配
Verifier 返回错误结果
Executor timeout
Context stale

看 Harness 是否：

• 能识别；
• 能阻断；
• 能恢复；
• 能给出正确 Trace。

Sensitivity Test（敏感性测试） ​

变化：

max_turns
tool exposure size
approval threshold
verification strictness

观察系统是否出现明显性能断点。

这能帮助找到：

Harness Policy 的合理 operating range（运行区间）。

因此：

Outcome Eval
→ 告诉你系统好不好

Causal Eval
→ 告诉你为什么好 / 为什么坏

Harness 发布时真正要控制什么 ​

通用的 Offline Eval（离线评测）→ Shadow（影子流量）→ Canary（小流量灰度）→ Rollback（回滚）发布链路统一由《企业级 Agent 平台参考架构》定义；本篇只保留 Harness 特有的发布对象：

harness_version
prompt_version
tool_exposure_policy
loop_control_policy
verification_policy

Harness 回归通常不会表现为“服务启动失败”，而会表现为任务级行为变化，例如无进展循环增多、Tool 选择变差、Verification 变松或 Human Intervention 上升。

因此 Harness 灰度的重点是：

固定 Model 和任务集，只改变 Harness 变量，并比较 Verified Success、Loop Length、Human Intervention、Cost 和 Failure Mix。

附录 A：高频架构问题与快速回答 ​

下面问题按概念、生产工程和企业架构分组；这里只保留快速回答，完整推导见正文。

A.1 核心概念与边界问题 ​

Q1：什么是 Agent Loop？ ​

30 秒答案

Agent Loop 是 Agent 根据当前 Context 和 State 做决策，执行 Action，读取 Observation，再根据新状态继续决策，直到满足结束条件的反馈闭环。

详细答案

核心不是“多轮”，而是：

Environment Feedback
→ Next Decision

如果 Tool Result 不进入下一轮决策，就只是 Tool Calling，不是完整的反馈式 Agent Loop。

追问

• 为什么需要 Stop Condition？
• Tool Result 和 Observation 有什么区别？
• Agent Loop 与 Workflow 有什么区别？

常见错误回答

“Agent Loop 就是模型一直调用工具。”

问题在于没有体现 Observation 反馈、State 更新和结束语义。

Q2：Agent Loop 和 Tool Calling 有什么区别？ ​

30 秒答案

Tool Calling 是一种“调用外部能力”的接口机制；Agent Loop 是一种“根据外部反馈持续决策”的运行机制。一个系统可以有 Tool Calling，但只调用一次就结束，因此不一定构成 Agent Loop。

详细答案

Tool Calling：

Model
→ Tool
→ Result
→ Answer

主要解决：

模型如何结构化表达“我要调用哪个能力、传什么参数”。

Agent Loop：

State / Context
→ Model
→ Action
→ Observation
→ State Update
→ Model
→ ...

主要解决：

外部环境变化如何重新影响下一步。

所以 Agent Loop 还需要：

• State；
• Stop / Controller；
• Observation；
• Failure Handling；
• Verification。

高分点

Tool Calling 是 Action Interface；Agent Loop 是 Control Flow + Feedback Semantics。

Q3：Agent Loop 和 Workflow 有什么区别？ ​

30 秒答案

Workflow 的 Control Flow 主要由开发者预先定义；Agent Loop 把一部分“下一步做什么”的决策权交给模型，根据环境反馈动态选择 Action。

详细答案

Workflow：

A → B → C

优点：

• 确定；
• 可测试；
• 可审计；
• 易做事务控制。

Agent Loop：

State
→ Model decides next action

优点：

• 适应不确定环境；
• 可以探索；
• 不需要穷举所有路径。

缺点是：

• 不确定性更大；
• 成本更难界定；
• 更依赖 Verification / Permission / Trace。

企业实践通常不是二选一，而是：

Deterministic Workflow
+
Agentic Decision Node

判断原则

已知流程用 Workflow；未知路径、需要反馈调整的部分交给 Agent。

Q4：最小 Agent Loop 有哪些核心部分？ ​

30 秒答案

可以分成 Loop Kernel 和 Control Envelope 两层。Loop Kernel 是 Context → Decision → Action → Observation → State Update；外层用 Task Contract、Termination 和 Verification 定义目标、约束和结束语义。

详细答案

推荐抽象：

Task Contract
Run State
Context
Decision
Action Proposal
Execution
Observation
State Update
Termination / Verification

其中真正每轮反复的是：

Context
→ Decision
→ Action
→ Observation
→ State Update

而：

Goal
Constraints
Success Criteria
Budget
Cancellation

更像控制外壳。

为什么这样分？

因为如果把 Goal、Budget、Action 都画成同一层，就很难解释：

• 哪些是每轮发生；
• 哪些是 Run 级约束；
• 哪些属于 Runtime；
• 哪些属于 Harness Policy。

高分点

最小 Loop 不一定需要显式 Plan、Memory 或 Multi-Agent；这些是按任务复杂度叠加的能力。

Q5：State 和 Context 有什么区别？ ​

30 秒答案

State 是系统真实保存的运行事实；Context 是从 State 和外部来源中选择后，某一轮真正送给模型看的信息投影。

详细答案

State 可能包含：

执行过哪些 Tool
Artifact
Budget
Approval
Plan Status
Failure Count

Context 可能只选择：

当前 Task
最近几轮
相关文件
最新错误
必要 Tool Schema

关系是：

State + External Sources
→ Selection / Compression / Policy Filter
→ Context
→ Model

为什么必须分开？

如果 State == Context：

• Context 压缩会破坏真实状态；
• 内部字段可能泄露给模型；
• Resume 时难以重建不同模型需要的输入；
• Runtime 数据结构被 Prompt 格式绑死。

高分点

State 是 source of truth；Context 是 model-visible projection。

Q6：Tool Result、Observation、Artifact 有什么区别？ ​

30 秒答案

Tool Result 是执行器的原始返回；Observation 是为下一轮决策加工后的模型可消费反馈；Artifact 是需要完整持久保存、供用户或后续系统使用的正式产物。

详细答案

例如 Shell 输出 20,000 行：

Raw Tool Result
= 20,000 行 stdout/stderr

Harness 可以生成：

Observation
= exit_code + root_error + important lines + artifact_ref

完整日志则保存成：

Artifact
= log.txt

这样可以同时满足：

• 模型 Context 不被淹没；
• Debug 时仍能找到原始证据；
• 下游系统可以消费完整产物。

Observation 还可能来自：

• Policy；
• Human Approval；
• Verifier；
• Subagent。

高分点

Observation 是 Agent 的“感知接口”，不只是 Tool Return。

Q7：Termination 和 Verification 有什么区别？ ​

30 秒答案

Termination 决定“Loop 为什么停止”；Verification 决定“任务是否满足成功条件”。一个 Run 可以因为超时而终止但失败，也可以因为模型请求 Finish 而进入 Verification 后被打回继续执行。

详细答案

Termination 原因可能是：

final output
max_turns
timeout
budget
cancel
hard failure

这些只是“停止原因”。

Verification 检查：

Success Criteria
→ Evidence
→ Pass / Fail

例如：

模型：修复完成
Termination Candidate: Finish Request

Verifier: integration test failed
→ verified_done = false
→ feedback to loop

所以：

terminated
≠
succeeded

更准确的 Run 状态应区分：

SUCCEEDED
FAILED
CANCELLED
BUDGET_EXCEEDED
TIMED_OUT

高分点

Finish Request 是模型决策；Success 是系统验证后的状态。

Q8：什么是 Agent Harness？ ​

30 秒答案

Harness 是围绕 Agent Loop 的生产工程控制层，负责 Context、Capability、授权决策的编排与模型外强制门禁、Loop Control、Verification、Trace 和 Extension 等机制；授权规则与最终决策仍由 Policy Owner 和 Policy Service 负责。它使一个“能循环的模型”变成“可生产运行的 Agent”。

详细答案

最小 Agent Loop 可能几十行代码就能工作，但一进入生产就会重复遇到：

模型看到什么？
能调用什么？
动作是否允许？
失败是否 Retry？
什么时候停止？
怎么判断真的完成？
怎么 Debug？
怎么扩展？

Harness 就是把这些横跨不同 Agent 的重复工程问题收敛成稳定机制。

它不是模型本身，也不等于 Sandbox / Runtime。可以记成：

Model
→ Intelligence

Loop
→ Feedback

Harness
→ Work Semantics + Control

真正企业级 Harness 的价值，不是“功能多”，而是让自主决策发生在受控、可验证、可观测、可扩展的边界内。

常见追问

• Harness 与 Framework 有什么区别？
• Harness Core 应该多厚？
• 强模型时代 Harness 会不会消失？

Q9：Harness、Runtime、Execution 怎么区分？ ​

30 秒答案

Harness
→ Agent 怎么干活

Runtime
→ 这次 Run 怎么可靠地活着

Execution
→ 动作在哪里真实发生

详细答案

Harness 主要关心：

Context
Capability
Permission
Loop Control
Verification

Runtime 主要关心：

Run State
Checkpoint
Retry / Resume
Scheduling
Concurrency
Durability

Execution 主要关心：

Filesystem
Shell
Browser
Container
VM
Sandbox

现实产品完全可以把三层打包在一起，但企业逻辑架构最好保持职责可分离，因为：

• Runtime 可能从本地进程升级为 Durable Runtime；
• Execution 可能从本机切换到 Sandbox / VM；
• Harness 的策略和 Context 逻辑不应该因此全部重写。

所以这里讨论的是逻辑边界，不是强制部署边界。

常见误区

“Claude Code 把执行环境也称作 harness 的一部分，所以 Harness 就必须包含 Sandbox。”

这是把 Product Boundary 和 Logical Architecture Boundary 混在一起。

Q10：为什么企业不能直接统一一个 Agent Framework？ ​

30 秒答案

因为 Framework 是实现载体，不是企业长期架构契约。模型、SDK 和框架会快速演进，而 Run / Tool Contract / Policy / Verification / Trace / Execution Contract 这些生产不变量更稳定。

详细答案

如果平台直接绑定：

Framework X Agent
Framework X Memory
Framework X Workflow
Framework X Tool

短期开发很快，但长期会遇到：

• Framework API 演进；
• 不同 Domain 需要不同运行模式；
• 新模型 / 新 Runtime 难迁移；
• 平台能力和某厂商抽象强耦合。

因此企业更应该统一“语义”和“Contract”：

什么叫 Run
什么叫 Capability
什么叫 Action / Observation
什么叫 Permission
什么叫 Verified Success

底层可以有多个 Framework Adapter。

这也是为什么企业 Agent Platform 最值得投资的是：

稳定边界，而不是押注单一框架。

A.2 生产工程问题 ​

Q11：Agent Loop 怎么避免死循环？ ​

高分答案结构：结论 → 失败机理 / 设计原理 → 工程方案 → 边界与权衡

详细答案

死循环至少有三类：

Exact Repeat
→ 同样的 Tool + 参数 + 错误重复

Semantic Repeat
→ 参数不同，但本质上在做同一件无效探索

Oscillation
→ A → B → A → B 来回震荡

所以完整防护不是一个 max_turns，而是：

Hard Budget
+ Action / Failure Fingerprint
+ Progress Signal
+ Retry Classification
+ Re-plan
+ Ask User / Escalation

max_turns 只负责最后兜底；真正提升成功率的是在耗尽预算前识别“为什么没有进展”。

Trade-off

过早判定死循环会杀死必要的长探索；过晚判断则成本爆炸。因此最好结合 Domain Verifier 和语义 Progress，而不是只看重复次数。

Q12：怎么判断 Agent 有没有 Progress？ ​

高分答案结构：结论 → 失败机理 / 设计原理 → 工程方案 → 边界与权衡

详细答案

Progress 不是“这一轮有没有 Tool Call”，而是：

当前 Run 是否更接近 Success Criteria。

可以观察：

State Delta
New Evidence
Artifact Delta
Plan Completion
Verifier Score
Failure Diversity

例如连续三轮搜索到了不同文件，并不一定代表有进展；如果新的 Evidence 没有缩小问题空间，就是假进展。

生产上通常不需要强行压成一个数学分数，但应该记录可比较的信号，并支持：

CONTINUE
REPLAN
SWITCH_CAPABILITY
ASK_USER
ESCALATE
STOP

常见误区

“换了 Tool 就说明有 Progress。”

Tool diversity 不等于 task progress。

Q13：Tool 太多怎么办？ ​

高分答案结构：结论 → 失败机理 / 设计原理 → 工程方案 → 边界与权衡

详细答案

Tool 太多主要带来四类问题：

Context Cost
Selection Confusion
Permission Surface
Operational Complexity

解决思路不是简单删除 Tool，而是把：

Global Capability Registry

和：

Model-visible Capability Set

分离。

模型每一轮只看到当前 Task / Phase / Identity / Environment 下最相关的一小部分能力。

更进一步可以使用：

• Tool Search；
• Semantic Routing；
• Capability Group；
• Skill 按需加载；
• Agent Profile。

Trade-off

过滤太激进会造成“能力不可见”；过滤太宽又回到 Tool Explosion。所以需要 Recall 与 Precision 的权衡。

Q14：Capability Routing 怎么设计？ ​

高分答案结构：结论 → 失败机理 / 设计原理 → 工程方案 → 边界与权衡

详细答案

Capability Routing 至少应该看五类信号：

Task Intent
Current Phase
Identity / Permission
Environment Availability
Risk / Cost

例如 Coding Agent 在“理解问题”阶段可能只暴露 read/search；进入“修复”阶段再暴露 edit/test；进入“提交”阶段才出现 git push / PR Tool。

推荐架构：

Registry
→ Candidate Retrieval
→ Policy Filter
→ Risk Filter
→ Ranking
→ Expose

Routing 的输出不是执行结果，而只是：

“这一轮模型可以选择哪些能力。”

Trade-off

Routing 本身也可能错，因此高价值 Tool 应支持显式发现、fallback search 和审计。

Q15：Permission 为什么不能只靠确认弹窗？ ​

高分答案结构：结论 → 失败机理 / 设计原理 → 工程方案 → 边界与权衡

详细答案

确认弹窗只是 Human-in-the-loop（人在回路）的一个 UI，不是权限模型。

真正的 Permission 至少要表达：

Who
→ User / Agent Identity

What
→ Resource

Action
→ Read / Write / Delete / Execute

Where
→ Sandbox / Staging / Production

Risk
→ Low / Medium / High

最终策略可能是：

ALLOW
ASK
DENY

即使用户点了“允许”，系统仍然应该校验资源范围和 Action Contract。

常见错误

把安全要求全部写进 System Prompt。这只能影响模型行为，不能形成强制安全边界。

Q16：Verification 放 Agent 还是 Harness？ ​

高分答案结构：结论 → 失败机理 / 设计原理 → 工程方案 → 边界与权衡

详细答案

两层 Verification 都需要，但职责不同。

Agent-level Verification

Agent 自己主动：

run tests
inspect diff
query status

它是智能行为的一部分。

Harness-enforced Verification

当模型请求 Finish 时，平台强制检查：

Completion Contract
→ Verifier
→ Evidence

它决定 Run 是否能进入 SUCCEEDED。

高风险场景不能只依赖第一层，因为模型可能：

• 忘记验证；
• 选择不完整测试；
• 错误理解结果。

最佳实践是：

Agent 主动验证提升效率，Harness 强制验证保证最终语义。

Q17：Parallel Tool Call 怎么设计？ ​

高分答案结构：结论 → 失败机理 / 设计原理 → 工程方案 → 边界与权衡

详细答案

并行的本质不是“Tool 是否支持 async”，而是：

多个 Action 之间是否存在共享状态与副作用冲突。

可以粗分：

Read-only + independent
→ parallel

Write + different isolated resources
→ possibly parallel

Write + same resource
→ serialize / lock

External side-effect
→ operation id + policy + dedup

还需要考虑 Observation 合并顺序：并行结果返回后，State Update 应有确定语义，避免不同完成顺序改变最终状态。

Trade-off

并行提升 Latency，但会增加冲突、Context 合并和 Trace 复杂度。

Q18：Harness Core 怎么避免膨胀？ ​

高分答案结构：结论 → 失败机理 / 设计原理 → 工程方案 → 边界与权衡

详细答案

Harness Core 膨胀通常因为平台看到一个业务需求，就把实现直接加进 Core。

判断一个能力是否应该进入 Core，可以问：

1. 是否跨 3 个以上 Domain 重复？
2. 语义是否稳定？
3. 是否必须统一治理？
4. 是否需要独立版本演进？
5. 是否可以通过 Extension Contract 实现？

推荐：

Stable Invariant
→ Core

Reusable but replaceable
→ Standard Capability

Domain-specific
→ Domain Extension

Durability / Scheduling
→ Runtime

Concrete execution
→ Execution

Core 越稳定，平台越能长期演进。

Q19：Plugin 怎么做版本治理？ ​

高分答案结构：结论 → 失败机理 / 设计原理 → 工程方案 → 边界与权衡

详细答案

Plugin 一旦进入企业生态，就已经接近基础设施依赖，至少需要：

plugin_id
semantic_version
required_harness_version
dependency_manifest
capability_manifest
permission_manifest