AI Agent Harness 的解剖结构（以及为何你的 Agent 在生产环境中失败）

很多人以为自己在构建”AI Agent”。

实际上，他们只是把模型和几个工具连接起来，然后就声称大功告成了。

这在演示中有效。但在生产环境中会失败。

模型忘记了刚刚发生的事情，工具调用静默失败，上下文窗口充满了噪音。到了这个阶段，很自然会去责怪模型。

但这通常是一种错误的诊断。

真正的问题在于模型周围的一切。

这个围绕周围的系统现在有一个名字：Agent Harness（Agent 骨架/框架）。

什么是 Agent Harness？

Agent 不是单个组件。它是一种涌现行为——当多个系统协同工作时出现的东西。

Harness（骨架）是产生这种行为的机制。

如果剥离一切，原始的 LLM 只是一个计算引擎。它没有持久内存，不与外部世界交互，也不管理跨步骤的状态。

Harness 填补了这些空白。

它处理编排、工具执行、记忆、上下文、安全和状态。换句话说，它将无状态的模型转变为可以行动的东西。

这里有一个有用的类比：原始模型就像没有操作系统的 CPU。Harness 就是让它可用的操作系统。

这种框架也澄清了一个常见的困惑。当有人说他们构建了一个”Agent”时，他们通常构建的是一个 Harness，然后将其连接到模型。

工程学的三个层次

要理解 Harness 的位置，需要将三个层次分开：

1. 1. 提示工程：模型接收什么指令
2. 2. 上下文工程：模型何时看到什么信息
3. 3. Harness 工程：其他一切——编排、工具、记忆、状态、安全

大多数人在第一个层次工作。强大的系统建立在第三个层次。

Harness 不是提示周围的薄包装。它是使迭代的、目标导向的行为成为可能的系统。

编排循环

每个 Agent 的核心是一个循环。

它通常被描述为一个思考-行动-观察周期：

1. 1. 组装提示
2. 2. 调用模型
3. 3. 解释输出
4. 4. 执行任何工具调用
5. 5. 将结果反馈到上下文中
6. 6. 重复直到完成

从概念上讲，这很简单。在许多实现中，它 literally 是一个 while 循环。

复杂性不是来自循环本身，而是来自循环必须正确管理的一切。

循环的运作方式

要理解各个部分如何结合在一起，看一个单一的周期会有帮助。

首先，系统构建完整的提示。这包括系统指令可用工具相关记忆对话历史和当前用户请求。

接下来，模型生成一个输出。这个输出可能是最终答案，也可能包含结构化的工具调用。

如果需要工具，Harness 会验证输入，在受控环境中执行它们，并捕获结果。

然后这些结果被格式化为模型可以理解的消息。系统更新其上下文并再次运行循环。

这持续到满足终止条件——例如，没有更多工具调用、最大步数或安全约束。

看起来像一个简单的循环实际上在协调多个子系统：上下文管理错误处理权限和状态跟踪。

系统实际在哪里失败

Agent 系统的大多数失败不是来自模型的推理能力。它们来自系统设计。

常见的失败点包括：

• • 上下文窗口充满低信号数据
• • 工具返回不一致或格式错误的输出
• • 缺乏重试或恢复机制
• • 没有验证中间结果

这些问题在步骤中累积。即使很小的每步失败率也可能导致多步工作流程崩溃。

结论很简单：可靠性是一个系统问题，而不仅仅是模型问题。

上下文管理是真正的约束

最被低估的挑战之一是上下文。

随着更多信息被添加到提示中，性能不会线性提高。在许多情况下，它会下降。重要的细节被埋没，模型变得不那么一致。

有效的系统将上下文视为有限的资源。

而不是将所有东西都倾倒到提示中，它们：

• • 总结过去的交互
• • 只在需要时检索相关信息
• • 分离短期和长期记忆
• • 将子任务委托给更小、更专注的循环

目标不是更多上下文，而是更好的上下文。

超越聊天历史的记忆

记忆在 Agent 系统中在多个层面运作。

短期记忆是当前对话。它提供即时连续性。

长期记忆跨会话持续存在——文件、数据库或结构化存储。

还有一种工作记忆的形式：执行期间发展的任务特定状态。

一个关键的设计原则是记忆不应该被盲目信任。强大的系统将存储的信息作为提示，并在根据当前状态行动之前验证它。

工具作为 Agent 的接口

工具是 Agent 与外部世界交互的方式。

它们通常通过描述每个工具做什么以及它期望什么输入的架构来定义。模型使用这些描述来决定何时以及如何调用它们。

Harness 负责围绕该决定的一切：

• • 注册可用工具
• • 验证输入
• • 安全执行（通常在沙箱中）
• • 将输出格式化回循环

设计糟糕的工具可能会像糟糕的提示一样降低性能。

框架如何实现这一模式

不同的框架收敛于相同的底层结构，但做出不同的架构选择。

尽管存在这些差异，核心模式仍然一致：一个循环、一组工具管理的上下文和有状态执行。

脚手架的视角

思考 Harness 的一种有用方式是将其视为脚手架。

它使模型能够超越其原始能力运行。它提供结构、范围和稳定性。

但它不做实际的工作。

随着模型的改进，一些责任从 Harness 转移到模型本身。系统倾向于演变为更简单的编排与更强大的底层模型。

这表明一个方向：最好的设计不会硬编码太多逻辑。它们允许系统随着模型变强而变简单。

薄 Harness 与厚 Harness

核心设计决策之一是 Harness 与模型之间有多少控制。

薄的 Harness将更多决策委托给模型。厚的 Harness更明确地编码更多逻辑。

两种方法都有效，但它们涉及灵活性可靠性和复杂性之间的权衡。

随着时间的推移，有一个明显的趋势向更薄的系统，因为模型在内部处理规划和执行方面变得更好。

关键洞察

两个系统可以使用相同的模型并产生完全不同的结果。

差异不是模型。

是 Harness。

Harness 决定如何管理上下文、如何使用工具、如何处理错误以及如何验证决策。

这是大部分工程杠杆所在。

结论

如果 Agent 失败，本能通常是更换模型。

在许多情况下，更好的做法是检查周围的系统。

因为模型只是故事的一部分。

Harness 是让它真正发挥作用的东西。