智能体架构深度解析

你可能已经构建了一个聊天机器人，或者通过一些工具连接了一个 ReAct 循环。在演示中它表现良好，但当你尝试构建生产级应用时，问题接踵而至：模型忘记了三步之前的操作、工具调用无声无息地失败、上下文窗口充斥着垃圾信息。

问题不在于你的模型，而在于模型周围的一切。

LangChain 证明了这一点：当他们仅改变封装 LLM 的基础设施（相同的模型，相同的权重）时，他们在 TerminalBench 2.0 上的排名从 30 名开外跃升至第 5 名。另一个研究项目通过让 LLM 优化基础设施本身，实现了 76.4% 的通过率，超越了人工设计的系统。

这种基础设施现在有了一个正式的名字：Agent Harness。

什么是 Agent Harness？

这个术语在 2026 年初被正式确立，但其概念早已存在。Harness 是封装 LLM 的完整软件基础设施，包括：编排循环、工具、记忆、上下文管理、状态持久化、错误处理和护栏（Guardrails）。Anthropic 的 Claude Code 文档简明扼要地指出：SDK 就是“驱动 Claude Code 的 Agent Harness”。OpenAI 的 Codex 团队也使用了同样的框架，明确将“Agent”和“Harness”等同，指代使 LLM 变得有用的非模型基础设施。

LangChain 的 Vivek Trivedy 曾给出一个经典的公式：“如果你不是模型，你就是 Harness。”

这里有一个容易混淆的区别：Agent 是涌现出的行为，即用户与之交互的、具有目标导向、能使用工具并能自我修正的实体；而 Harness 则是产生这种行为的机器。当有人说“我构建了一个 Agent”时，他们真正的意思是构建了一个 Harness 并将其指向一个模型。

Beren Millidge 在其 2023 年的论文中将这一类比精确化：原始 LLM 就像是没有 RAM、没有硬盘且没有 I/O 的 CPU。上下文窗口充当 RAM（快速但有限），外部数据库充当硬盘存储（大但慢），工具集成充当设备驱动程序。而 Harness 就是操作系统。正如 Millidge 所写：“我们重新发明了冯·诺依曼架构，因为它是任何计算系统的自然抽象。”

工程化的三个层面

围绕模型存在三个同心圆式的工程层面：

• 提示词工程 (Prompt Engineering)：精心设计模型接收的指令。
• 上下文工程 (Context Engineering)：管理模型在何时看到什么内容。
• Harness 工程：涵盖上述两者，加上整个应用基础设施：工具编排、状态持久化、错误恢复、验证循环、安全执行和生命周期管理。

Harness 不是提示词的包装器，它是使自主 Agent 行为成为可能的完整系统。

生产级 Harness 的 12 个核心组件

综合 Anthropic、OpenAI、LangChain 及广泛的从业者社区经验，一个生产级 Agent Harness 包含以下 12 个组件：

1. 编排循环 (The Orchestration Loop)

这是系统的核心心跳。它实现了“思考-行动-观察”（TAO）循环，也称为 ReAct 循环。该循环运行流程为：组装提示词、调用 LLM、解析输出、执行工具调用、反馈结果，如此循环直到任务完成。

从机械角度看，它通常只是一个 while 循环。复杂性在于循环所管理的内容，而非循环本身。Anthropic 将其运行时描述为一个“哑循环”，所有的智能都存在于模型中，Harness 仅负责管理轮次。

2. 工具 (Tools)

工具是 Agent 的“手”。它们被定义为注入 LLM 上下文的 Schema（名称、描述、参数类型）。工具层负责注册、Schema 验证、参数提取、沙箱化执行、结果捕获，并将结果格式化为 LLM 可读的观测值。

3. 记忆 (Memory)

记忆在多个时间尺度上运行。短期记忆是单次会话中的对话历史。长期记忆则跨会话持久化：Anthropic 使用项目文件和自动生成的内存文件；LangGraph 使用命名空间组织的 JSON 存储；OpenAI 则支持由 SQLite 或 Redis 支持的会话。

4. 上下文管理 (Context Management)

这是许多 Agent 失败的隐形原因。核心问题是“上下文腐烂”：当关键内容落在窗口中间位置时，模型性能会下降 30% 以上（即“迷失在中间”现象）。

生产环境的策略包括：

• 压缩：在接近限制时总结对话历史。
• 观测掩码：隐藏旧的工具输出，但保留工具调用记录。
• 即时检索：保持轻量级标识符并动态加载数据。
• 子 Agent 委派：每个子 Agent 进行广泛探索，但仅返回精简后的摘要。

5. 提示词构建 (Prompt Construction)

这决定了模型在每一步实际看到的内容。它是分层的：系统提示词、工具定义、记忆文件、对话历史和当前用户消息。

6. 输出解析 (Output Parsing)

现代 Harness 依赖于原生工具调用，模型返回结构化的 tool_calls 对象而非需要解析的自由文本。Harness 会检查：是否有工具调用？如果有，执行并循环；如果没有，则为最终答案。

7. 状态管理 (State Management)

LangGraph 将状态建模为流经图形节点的类型化字典。检查点（Checkpointing）发生在步骤边界，允许在中断后恢复和进行“时间旅行”调试。Claude Code 则采用不同的方法：将 Git 提交作为检查点，将进度文件作为结构化草稿本。

8. 错误处理 (Error Handling)

一个 10 步的过程，如果每步成功率为 99%，端到端成功率仅约 90.4%。错误会迅速累积。 Harness 需要区分错误类型：瞬时错误（退避重试）、LLM 可恢复错误（将错误作为工具消息返回以便模型调整）、用户可修复错误（中断以请求人工输入）以及意外错误。

9. 护栏与安全 (Guardrails and Safety)

OpenAI 的 SDK 实现了三个级别：输入护栏、输出护栏和工具护栏。Anthropic 在架构上将权限执行与模型推理分离：模型决定尝试做什么，而工具系统决定允许做什么。

10. 验证循环 (Verification Loops)

这是区分玩具演示与生产级 Agent 的关键。Anthropic 建议采用三种方法：基于规则的反馈（测试、Linter）、视觉反馈（截图）和 LLM 作为裁判（由另一个子 Agent 评估输出）。

11. 子 Agent 编排 (Subagent Orchestration)

支持多种执行模式：Fork（父上下文的精确副本）、Teammate（独立的终端面板）和 Worktree（独立的 Git 工作区）。

循环运行机制：步骤详解

让我们追踪这些组件在单个周期中是如何协作的：

1. 提示词组装：Harness 构建完整输入，将重要上下文置于提示词的开头和结尾。
2. LLM 推理：提示词发送至模型 API，模型生成文本、工具调用请求或两者。
3. 输出分类：如果没有工具调用，循环结束；如果有，进入执行阶段。
4. 工具执行：Harness 验证参数、检查权限并在沙箱中执行。
5. 结果封装：工具结果被格式化为消息，捕获错误以便模型自我修正。
6. 上下文更新：结果追加到历史记录，必要时触发压缩。
7. 循环：返回第一步，直到满足终止条件。

主流框架的实现模式

• Anthropic Claude SDK：通过单个 query() 函数暴露 Harness，运行时是一个“哑循环”，智能完全在模型中。
• OpenAI Agents SDK：采用“代码优先”模式，通过 Runner 类实现，工作流逻辑使用原生 Python 表达。
• LangGraph：将 Harness 建模为显式状态图，通过节点和条件边控制路由。
• CrewAI：实现基于角色的多 Agent 架构，将 Harness 封装在 Agent 定义中（角色、目标、背景故事）。
• AutoGen：由微软开发，支持顺序、并发、群聊、移交等五种编排模式。

脚手架隐喻

“脚手架”这一比喻非常精确。建筑脚手架是使工人能够到达原本够不到的地方的临时基础设施。它本身不负责施工，但没有它，工人无法到达高层。

关键洞察在于：当建筑完工时，脚手架会被拆除。随着模型能力的提升，Harness 的复杂性应该降低。

这指向了协同进化原则：现在的模型在训练时就已经将特定的 Harness 纳入循环。改变工具实现可能会因为这种紧密耦合而导致性能下降。

定义 Harness 的七个关键决策

每个 Harness 架构师都面临七个选择：

1. 单 Agent vs. 多 Agent：优先最大化单 Agent 能力，仅在工具过载或任务域明显分离时拆分。
2. ReAct vs. 计划执行：ReAct 灵活但成本高；计划执行分离了规划与执行，速度更快。
3. 上下文窗口管理策略：在保留推理痕迹的同时，尽可能减少 Token 使用。
4. 验证循环设计：确定是使用确定性的计算验证还是语义性的 LLM 验证。
5. 权限与安全架构：在“宽容（快速但冒险）”与“严格（安全但缓慢）”之间权衡。
6. 工具范围策略：工具越多往往性能越差，应暴露当前步骤所需的最小工具集。
7. Harness 的厚度：决定多少逻辑留在 Harness 中，多少交给模型。

Harness 即产品

使用相同模型的两个产品，其性能可能因 Harness 设计的不同而产生巨大差异。TerminalBench 的证据表明：仅改变 Harness 就能让 Agent 的排名移动 20 位以上。

Harness 并非已解决的问题，也不是一个简单的商品层。它是硬核工程的所在地：将上下文视为稀缺资源进行管理、设计防止错误累积的验证循环、构建无幻觉的记忆系统，以及决定构建多少脚手架。

随着模型改进，Harness 正趋向于变薄，但它不会消失。即使是最强大的模型，也需要系统来管理其上下文、执行工具、持久化状态并验证其工作。

下次当你的 Agent 失败时，不要只责怪模型，请检查你的 Harness。

• 原文链接： x.com/akshay_pachaar/sta...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～