2 min read#agent#harness#orchestration#agent-engineering#codex

Agent Harness

Apr 7, 2026

Agent Harness 是包裹在 LLM 外部、管理 agent 完整生命周期的运行时基础设施。

$\text{Agent} = \text{Model} + \text{Harness}$

模型负责推理和生成文本；harness 决定模型看到什么上下文、能调用什么工具、何时停止、出错如何恢复。这个概念由 OpenAI 在 2025 年底基于 Codex 团队的实践经验正式提出——3 名工程师借助 AI agent 在 5 个月内构建了百万行生产代码，而核心经验不是模型能力，而是 harness 的设计质量。

为什么需要 Harness

裸模型（即使是最强的 LLM）直接用于复杂、多步骤任务时，可靠性很低。瓶颈通常不在模型的推理能力，而在于：

模型不知道该用什么工具、不知道项目的约定和约束
长任务中上下文逐渐失焦，遗忘早期指令
出错后没有恢复机制，错误会在后续步骤中放大
没有验证环节，无法判断输出是否正确

Harness 的作用就是系统性地解决这些问题。LangChain DeepAgents 的实验证明：仅改变 harness（模型不变），任务完成率可以从 60% 提升到 98%。

Harness vs Framework vs Runtime

概念	角色	类比
Framework（LangChain, CrewAI）	构建时组件库：prompt 模板、工具抽象、memory 接口	施工套件
Runtime（Temporal, DBOS）	执行引擎：持久化、状态恢复、并发管理	引擎
Harness（Claude Code, Codex harness）	完整运行时系统：框架 + 运行时 + 默认配置 + 护栏 + 验证	整车

Framework 是构建 agent 的工具，harness 是 agent 运行的环境。一个直观的类比：模型是 CPU，上下文窗口是 RAM，harness 是操作系统。

核心组件

1. 上下文工程(Context Engineering)

管理模型在每一步”看到什么”。这是 harness 中影响最大的杠杆。

三级渐进加载：Tier 1（始终在上下文中，如 AGENTS.md）→ Tier 2（按需加载的领域文档）→ Tier 3（冷存储，通过工具从磁盘读取）
Prompt caching：保持上下文前缀稳定，利用 kv-cache 的缓存命中降低成本（缓存 token 成本约为非缓存的 1/10）
文件系统作为外部记忆：plan、progress、中间结果写入文件而非塞满上下文窗口
保留错误信息：失败的 tool call 和 stack trace 留在上下文中，防止重复犯错

2. 工具集成(Tool Integration)

连接模型与外部能力：代码执行、文件读写、web 搜索、API 调用等。

关键设计原则：

agent 应该拥有和人类工程师相同的工具集
工具的错误消息应同时包含”哪里错了”和”如何修复”——工具不只是执行器，也是教学机制
通过 logit masking 限制可用工具（而非直接移除，以保持 KV cache 有效）

3. 验证与护栏(Verification & Guardrails)

每次 agent 输出后的质量检查，形成反馈闭环。

两种控制方向：

前馈控制(Guides)：在行动前引导——架构文档、类型检查、linter 规则、编码规范
反馈控制(Sensors)：在行动后检测——测试套件、静态分析、AI 代码审查

两种实现方式：

确定性的（linter、test、schema validation）：快速、可靠、便宜
推理性的（LLM-based review）：语义级别、但非确定性、较慢

生产系统通常交替使用确定性和 agent 节点：写代码(agent) → linter(确定性) → 修复(agent) → 测试(确定性) → 修复(agent, 最多 2 次) → 失败则升级给人类。

4. 状态与记忆(State & Memory)

层级	内容	生命周期
上下文窗口	当前模型实际看到的	当前 turn
会话状态	对话历史、工具结果、工作笔记	当前 session
持久存储	长期状态、transcript、progress 文件	跨 session

Harness 负责在这三层之间搬运信息：从磁盘选择性读取到会话，再组装进上下文；重要状态在丢弃前写回磁盘。

5. 编排(Orchestration)

管理多步骤、多 agent 的协作流程。

常见模式：

单 agent 循环：READ → PLAN → ACT → OBSERVE → CHECKPOINT，适合大多数任务
Orchestrator-Worker：主 agent 拆解任务，分发给专门化的 worker agent
Initializer-Coder：初始化阶段创建 scaffold 和 feature spec，然后逐 feature 实现，每个 feature 一个独立 session

OpenAI 的四个 Harness 实践

基于 Codex 团队的百万行代码经验：

架构即护栏

用严格的分层架构约束 agent 的解空间。例如固定依赖方向（Types → Config → Repo → Service → Runtime → UI），用自定义 linter 机械地执行约束。agent 不需要”理解”架构，只需在违反时收到明确的错误信息。

工具即基础和反馈

Agent 需要和人类工程师完全一致的工具链。Linter 的错误消息既标注违规也提供修复建议——工具在执行过程中同时充当教学机制。

文档作为活系统（AGENTS.md）

仓库根目录的 AGENTS.md 文件在每次 session 开始时自动被 agent 读取。内容包括构建命令、测试方法、代码规范、已知陷阱。关键原则：agent 每次犯错后立刻更新 AGENTS.md，确保同一错误不再重复。

AGENTS.md 应是”目录”（约 100 行），而非百科全书——具体内容用指针指向结构化的 docs/ 目录。

验证和质量门

每次输出通过 pre-commit hook、linter、结构测试。失败反馈给模型重试。人类 review 架构完备性，而非逐行代码。定期运行”垃圾回收” agent 检测技术债和规范违反。

生产架构模式

模式	代表	特点
单线程主循环	Claude Code	扁平消息列表，subagent 限于单层深度
中间件栈	LangChain DeepAgents	类 Express.js 的 hook：`before_agent`、`wrap_model_call`、`before/after_tool_call`
协议优先 App Server	OpenAI Codex	Thread/Turn/Item 原语，双向 JSON-RPC，多端复用
Initializer + Worker	Anthropic 长任务模式	初始化创建 feature_list.json，worker agent 逐个实现

工程师角色的转变

在 harness engineering 范式下，工程师从”写代码”转向”设计环境”：

环境构建：设计架构约束、工具链、反馈闭环
工作管理：规划任务、编写 spec、审查输出、维护架构标准
Harness 迭代：每当 agent 犯错，工程化地消除该类错误的可能性

Mitchell Hashimoto 的表述：每当 agent 犯了一个错误，就花时间设计一个方案让它永远不再犯这个错误。