Agent Harness 解剖：从概念到工程实践
Agent Harness 解剖：从概念到工程实践
Akshay Pachaar 在 2026 年 4 月发表的深度分析，综合 Anthropic、OpenAI、LangChain 等团队的实践经验，系统定义了 Agent Harness（代理框架）——将无状态 LLM 转化为可用智能体的完整软件基础设施。
核心观点#
- Agent 是涌现行为，Harness 是产生该行为的机器。当有人说"我构建了一个 agent"，实际是说"我构建了一个 harness 并指向了一个模型"。
- Beren Millidge 的类比：原始 LLM = 没有 RAM、没有磁盘、没有 I/O 的 CPU；上下文窗口 = RAM；外部数据库 = 磁盘；工具集成 = 设备驱动；harness = 操作系统。
- "如果你不是模型，你就是 harness。"——LangChain 的 Vivek Trivedy
- TerminalBench 2.0 证据：仅改变 harness（相同模型、相同权重），排名从 30+ 跃升至第 5。
- Harness 是产品差异化的真正战场：使用相同模型的两个产品，性能差异完全来自 harness 设计。
围绕模型的三个工程层次#
- 提示工程（Prompt Engineering）——设计模型收到的指令
- 上下文工程（Context Engineering）——管理模型看到什么、何时看到
- Harness 工程（Harness Engineering）——包含以上两者，再加上完整应用基础设施
生产级 Harness 的 12 个组件#
| # | 组件 | 说明 |
|---|---|---|
| 1 | 编排循环（Orchestration Loop） | TAO/ReAct 循环的核心 while 循环；Anthropic 称其为"dumb loop"，所有智能在模型中 |
| 2 | 工具（Tools） | Handler 的六大类和 OpenAI 的函数工具、托管工具、MCP 服务器工具 |
| 3 | 记忆（Memory） | 三层级短/长期记忆；Claude Code 的轻量索引 → 主题文件 → 原始转录 |
| 4 | 上下文管理（Context Management） | 压缩、观测遮蔽、即时检索、子代理委派——对抗"Lost in the Middle" |
| 5 | 提示构造（Prompt Construction） | 系统提示 → 工具定义 → 记忆文件 → 对话历史 → 用户消息的层次化组装 |
| 6 | 输出解析（Output Parsing） | 原生工具调用为主；结构化输出用 Pydantic 约束 schema |
| 7 | 状态管理（State Management） | LangGraph 的类型化字典 + Reducer；Claude Code 的 git 提交 + 进度文件 |
| 8 | 错误处理（Error Handling） | 10 步流程若每步 99% 成功率，最终仅 ~90.4%；四种错误类型分级处理 |
| 9 | 护栏与安全（Guardrails & Safety） | 三层护栏（输入、输出、工具）；Claude Code 独立管控约 40 项工具权限 |
| 10 | 验证循环（Verification Loops） | 规则反馈 + 视觉反馈 + LLM-as-judge；Boris Cherny：验证使质量提升 2-3 倍 |
| 11 | 子代理编排（Subagent Orchestration） | Fork / Teammate / Worktree 三种执行模型 |
| 12 | 生命周期管理 | 构建、部署、监控、更新的完整生命周期 |
循环在行动：单步工作流#
- 提示组装 → 系统提示 + 工具 schema + 记忆 + 对话历史 + 用户消息（关键上下文放首尾）
- LLM 推理 → 模型生成文本和/或工具调用请求
- 输出分类 → 判断是否调用工具；是否请求切换 agent
- 工具执行 → 参数校验 → 权限检查 → 沙箱执行 → 捕获结果（只读并发，变异串行）
- 结果打包 → 格式化为 LLM 可读消息；错误捕获让模型自纠正
- 上下文更新 → 追加结果；接近窗口上限时触发压缩
- 循环 → 回到步骤 1，直到满足终止条件
Ralph Loop 模式（Anthropic 长任务方案）：Initializer Agent 初始化环境 → Coding Agent 在每次会话中读取 git 日志和进度文件定向 → 选取优先级最高的未完成任务 → 工作、提交、写摘要。文件系统提供跨上下文窗口的连续性。
主流框架实现对比#
| 框架 | 核心理念 | 架构特点 |
|---|---|---|
| Claude Agent SDK | "Dumb loop" | 通过单一 query() 创建循环；所有智能在模型；Gather-Act-Verify 循环 |
| OpenAI Agents SDK | Code-first | Runner 类三模式（async/sync/stream）；Codex 三层架构（Core → App Server → Client） |
| LangGraph | 显式状态图 | llm_call 和 tool_node 两个节点 + 条件边；从 AgentExecutor 演进而来 |
| CrewAI | 角色式多 agent | Agent / Task / Crew 三层；Flows 层提供确定性骨架 |
| AutoGen | 对话驱动编排 | 三层架构（Core / AgentChat / Extensions）；五种编排模式 |
设计 Harness 的 7 个关键决策#
- 单 agent vs. 多 agent：优先最大化单 agent；仅在工具超过 ~10 个重叠或领域明确分离时才拆分
- ReAct vs. Plan-and-Execute：ReAct 灵活但单步成本高；LLMCompiler 报告 3.6 倍 速度提升
- 上下文窗口管理策略：五种方案；ACON 研究实现 26-54% token 缩减，准确率保持 95%+
- 验证循环设计：计算验证（确定性地基）vs. 推理验证（LLM-as-judge，语义检查）
- 权限与安全架构：宽松型（快速但有风险）vs. 限制型（安全但慢）
- 工具范围策略：更多工具通常更差——Vercel 移除 80% 工具 后效果更好；Claude Code 通过懒加载实现 95% 上下文缩减
- Harness 厚度：逻辑放在 harness 还是模型中？Anthropic 押注薄 harness + 模型改进
核心启示#
- 脚手架隐喻：Harness 是建筑脚手架——建造时不可缺少，建筑完成后拆除。随着模型改进，harness 复杂度应降低。
- 共演化原则：模型现在与特定 harness 联合训练；改变工具实现可能降低性能。
- 未来验证测试：如果更强模型到来时不需要增加 harness 复杂度，设计就是合理的。
- Manus 的教训：六个月内重建五次，每次都在移除复杂度。复杂工具定义退化为通用 shell 执行；"管理 agent" 退化为简单的结构化交接。
- 最终结论：当下次 agent 失败时，不要责怪模型。审视 harness。
AI 整理页
基于 1 篇可追溯原文整理，可能有误。来源、版本与反馈入口收在下方。