---
author: Best Partners TV
date: '2026-04-24'
guest: ''
layout: post.njk
source: https://www.youtube.com/watch?v=S36ri23-l60
speaker: Best Partners TV
tags:
  - agent-harness
  - orchestration-loop
  - context-management
  - tool-calling
  - ai-architecture
title: Agent Harness：十二大模块深度解析与未来趋势
summary: 本视频深入解析了Agent Harness的核心概念、十二大模块及其在生产级AI智能体中的关键作用。内容涵盖了编排循环、工具、记忆、上下文管理、提示词组装、工具调用、状态与检查点、错误处理、护栏、验证与反馈、子Agent编排以及初始化与环境搭建。视频还对比了Anthropic、OpenAI、LangGraph、CrewAI、AutoGen等主流框架的设计哲学，并探讨了Harness与模型共同进化的趋势及七大架构抉择，强调了Harness工程在未来AI竞争中的核心地位，并指出“模型不行”往往是Harness架构不完善的根本原因。
insight: ''
draft: true
series: ''
category: ai-ml
area: tech-engineering
project: []
people: []
companies_orgs:
  - Anthropic
  - OpenAI
  - LangChain
products_models:
  - Claude Agent SDK
  - OpenAI Agents SDK
  - LangGraph
  - CrewAI
  - AutoGen
media_books: []
status: evergreen
---
大家好，这里是最佳拍档，我是大飞。今天这期视频，我们再来聊 Harness。最近，**Anthropic**、**OpenAI**、**LangChain**、**Perplexity** 这些全球顶流团队全都在疯狂加码这个赛道。甚至有人断言，未来 AI 的竞争不再是模型参数的内卷，而是 Harness 架构的博弈。

### Agent Harness 的定义与痛点
为什么需要 Agent Harness 呢？这就必须提到行业里目前普遍存在的一个痛点：很多开发的智能体，演示时流畅无比，可一旦放到生产环境，立马原形毕露，任务成功率断崖式下跌。绝大多数开发者的第一反应是：模型不行，要换更强的模型。但真相是，问题从来不在模型本身，而在模型周围的那套基础设施。

LangChain 用一个实验狠狠打醒了整个行业：他们完全没改动模型权重和底层算法，只优化了包裹大语言模型的 Harness 架构，就让智能体在 TerminalBench 2.0 评测中，从 30 名开外直接飙升至第 5 名。还有研究团队让 LLM 自主优化 Harness 架构，任务通过率直接冲到 76.4%，吊打所有人工设计的系统。这就是 Agent Harness 的威力。

2026年初，这个术语被全球 AI 社区正式定义。但是它的理念，其实早就已经渗透在每一个生产级 AI 应用里。简单来说，**Agent Harness** 就是包裹大语言模型的一整套操作系统级软件基础设施。它把一个只会输出文本、无状态、容易出错的裸大语言模型，变成有目标、会用工具、能纠错、可持久运行的、靠谱的智能体。

LangChain 的维韦克·特里维迪（Vivek Trivedy）说过一句被行业奉为经典的话：“如果你不是模型，你就是 Harness。” 这句话其实道破了核心的本质：我们日常说的搭建一个智能体，本质上从来不是创造一个会思考的 AI，而是要搭建一套 Harness，再把它对接给模型。

### Harness 的类比：操作系统与 CPU
为了让大家方便理解，我们用计算机架构做一个精准类比，这也是 AI 领域公认最贴切的解释。

裸的大语言模型就像一台没有内存、没有硬盘、没有外设驱动的 CPU，只有核心计算能力，无法独立完成任何实际任务。
*   **上下文窗口** 充当临时内存（Temporary Memory），速度快但容量有限。
*   **向量数据库与长期存储** 充当硬盘（Long-term Storage），容量大但响应较慢。
*   **工具集成** 就是设备驱动（Device Driver），让模型能调用外部能力。

而 Agent Harness，就是让这一切协同工作的**操作系统**（Operating System）。

贝伦·米利奇（Beren Millidge）在 2023 年的《AI 的脚手架》一文中更是直言：“我们通过 Agent Harness，重新发明了**冯·诺依曼架构**（Von Neumann Architecture）”。应该说，这不是所谓简单的技术封装，而是计算系统发展的一种必然抽象，是任何 AI 智能体在走向实用过程中都绕不开的底层逻辑。

### Harness 的十二大核心模块
在详细拆解 Harness 之前，我们先要理清三个容易混淆的工程层级，这也是理解 Harness 的基础：
1.  **第一层**是**提示工程**（Prompt Engineering）：专注于打磨模型接收的指令，让模型更精准理解需求。
2.  **第二层**是**上下文工程**（Context Engineering）：核心是管理模型在不同阶段能看到哪些信息，避免信息过载。
3.  **第三层**则是**Harness 工程**（Harness Engineering）：它涵盖了前两者，更囊括了工具编排、状态持久化、错误恢复、验证循环、安全管控、生命周期管理等全套的应用基础设施。

很多人误以为 Harness 只是给提示词套个壳，这其实是完全错误的认知。Harness 不是简单的包装，而是一套让自主智能体实现自主思考、自主行动、自主修复的完整系统，也是所谓玩具级的 Demo 与生产级的智能体之间的本质区别。

综合 Anthropic、OpenAI、LangChain 以及全球 AI 工程社区的最佳实践，我们可以得出一个结论：一个真正能落地的生产级 Agent Harness，需要由**十二个完全独立、环环相扣的核心模块**组成，少了任何一个，都无法支撑稳定的智能体运行。这也正是我们今天这期视频要重点拆解的部分。

#### 1. 编排循环（Orchestration Loop）
它是整个智能体的心跳，是所有行为的核心引擎。我们常说的 **ReAct 循环**（Reasoning-Action Loop），以及**思考-行动-观察（TAO）循环**（Think-Act-Observe Loop），本质上都是编排循环的具体实现。

它的运行逻辑非常清晰：先组装完整提示词，将系统指令、工具信息、记忆内容、对话历史整合后，发送给大模型；等待模型输出后解析内容，判断是否需要调用工具；执行工具调用后将结果返回给模型；重复这个流程，直到任务完成或触发终止条件。

从代码结构来看，编排循环往往只是一个简单的 `while` 循环，看似毫无技术含量，但真正的复杂度全藏在循环管理的细节里，而非循环本身。Anthropic 对自家编排循环的定位很有意思，他们称之为**笨循环**（Dumb Loop），也就是所有的智能决策、逻辑思考都由模型完成，Harness 的运行时只负责按流程转场、调度任务，不参与核心推理。这种设计的优势在于，让模型专注于智能输出，Harness 专注于稳定执行，分工明确，大幅降低系统复杂度。

但是，无论是简单的问答任务，还是复杂的代码重构、数据分析，所有智能体的行为，都始于编排循环，也终于编排循环。它是整个 Harness 架构的动力核心。

#### 2. 工具（Tools）
如果说编排循环是智能体的心跳，那工具就是智能体的手，是它与现实世界交互的唯一途径。工具不是随意的函数调用，而是以标准化 Schema 形式定义的能力集合，包含工具名称、功能描述、参数类型、返回格式。通过注入模型上下文，让模型明确自己具备哪些操作能力。

工具层的职责远不止是调用这么简单，它还要完成工具注册、 Schema 校验、参数提取、沙箱执行、结果捕获，最后把执行结果格式化成模型能读懂的观察信息，再回传给编排循环。如果没有完善的工具层，模型就算有再强的推理能力，也只能停留在文本输出，无法落地任何实际操作。

目前行业的头部厂商都已经构建了完善的工具体系。比如 **Anthropic 的 Claude Code** 提供六大类核心工具，覆盖文件操作、搜索、命令执行、网页访问、代码智能、子智能体孵化。OpenAI 的 Agents SDK 支持三类工具：分别是函数调用工具、官方托管工具（包括联网搜索、代码解释器、文件检索等等），以及 MCP 服务器工具，满足不同场景的能力需求。

简单来说，工具层的设计直接决定了智能体的能力边界。

#### 3. 记忆（Memory）
它是智能体跨越时间尺度、保持任务连续性的关键，让智能体不再像鱼的记忆一样。Harness 的记忆体系不是单一存储，而是在多个时间维度同时运作，分为短期记忆与长期记忆。

*   **短期记忆**：就是单次会话内的对话历史，记录当前任务的所有交互信息，确保模型在多轮对话中不脱节。
*   **长期记忆**：则实现跨会话持久化，即便智能体重启、服务中断，也能保留之前的任务进度、决策记录。

不同框架的长期记忆实现方式各有特色：Anthropic 通过 `claude.md` 项目文件和自动生成的 `MEMORY.md` 实现持久化；LangGraph 采用按命名空间组织的 JSON 存储；OpenAI 则支持基于 SQLite 或 Redis 的会话存储，兼顾性能与稳定性。

**Claude Code 的三级记忆层级设计**堪称行业标杆：
1.  第一层是轻量级索引，单条约 150 字符，常驻内存，快速响应。
2.  第二层是详细主题文件，按需加载，平衡容量与速度。
3.  第三层是原始交互记录，仅通过搜索访问，保证数据完整性。

这里有一个核心设计原则：智能体不会完全依赖记忆，而是将记忆作为一种提示，行动前会与实际状态核对验证，避免因记忆错误导致任务失败。

#### 4. 上下文管理（Context Management）
这是生产级智能体最容易默默翻车的重灾区，也是所有 AI 工程师必须攻克的难题。核心痛点只有一个：**上下文腐烂**（Context Rot）。

斯坦福大学的《Lost in the Middle》研究与 Chroma 团队的实验相互印证了一个结论：当关键信息落在上下文窗口中间位置时，模型的性能会暴跌 30% 以上。即便如今主流模型已经支持百万级的 Token 上下文了，随着内容的不断膨胀，模型的指令遵循能力、推理准确率仍然会持续下降。

为了解决这个问题，生产环境已经形成了一套成熟的应对策略：
1.  **压缩**（Compaction）：当上下文接近上限时，对对话历史做摘要处理，保留核心决策和未解决的问题，丢弃冗余的工具输出。
2.  **观察屏蔽**（Observation Masking）：隐藏旧的工具输出细节，但是保留工具调用记录，这样既能减少 Token 消耗，又不丢失关键逻辑。
3.  **即时检索**（Just-in-time Retrieval）：维护轻量级索引，动态加载所需数据。比如 Claude Code 用 `grep`、`glob`、`head`、`tail` 命令精准提取内容，而非加载完整文件。
4.  **子智能体委派**（Sub-agent Delegation）：将复杂任务拆分给子智能体探索，最终只返回 1000-2000 个 Token 的精简摘要，大幅降低主智能体的上下文压力。

Anthropic 的上下文工程指南中，明确了这一步的终极目标：那就是找到**最小的高信噪比 Token 集合**，用最少的关键信息，最大化实现预期任务效果。这是上下文管理的核心准则。

#### 5. 提示词组装（Prompt Assembly）
它定义了模型在每一轮推理中看到的世界，是连接上下文、记忆、工具、用户需求的最后一环。提示词组装不是简单的拼接，而是分层堆叠的结构化过程，优先级明确、逻辑清晰。

标准的组装顺序通常是：先通过**系统提示词**（System Prompt）定义智能体的身份和核心规则，再通过**工具定义**（Tool Definitions）告知可用的能力，然后通过**记忆文件**（Memory Files）总结历史经验，进而根据**对话历史**（Dialogue History）获取当前的任务进度，最后再根据当前用户的消息得到**最新需求**（User Message）。

OpenAI 的 Codex 则采用了严格的**优先级栈**：服务器控制的系统消息优先级最高，随后依次是工具定义、开发者指令和用户指令，最后才是对话历史。这种设计确保核心规则不会被冗余信息覆盖，保证智能体行为不偏离预期。

在实际应用过程中，提示词组装的质量直接会影响模型的输出准确率，这也是 Harness 工程中最考验工程师细节把控能力的环节。

#### 6. 工具调用与结构化输出（Tool Calling & Structured Output）
它是模型与 Harness 之间的通用语言，解决了传统自由文本输出难以解析、容易出错的问题。现代生产级 Harness 完全依赖原生工具调用，模型不再输出模糊的自然语言指令，而是直接返回标准化的 `tool_calls` 结构化对象，包含工具名称、参数值等明确信息。

这样一来，Harness 的判断逻辑就变得极为简单：只需要解析模型输出，如果存在工具调用，就执行对应工具并继续循环；如果没有工具调用，直接将模型输出作为最终答案，终止循环。

对于结构化输出，OpenAI 和 LangChain 都支持通过 **Pydantic 框架**（Pydantic Framework）进行 Schema 约束，确保输出的格式符合预期，降低解析失败率。当然，一些遗留方案在边缘场景仍然有用，比如 `RetryWithErrorOutputParser` 会将原始的提示词、失败输出和解析错误一并返回给模型，让模型自主修正，但是这种方式效率较低，只建议作为补充方案使用。

#### 7. 状态与检查点（State & Checkpointing）
它是智能体实现断点续跑、可回溯和可调试的核心，解决了长周期任务中断后无法恢复的痛点。长流程任务，比如大型项目代码重构、多步骤数据分析，可能持续几个小时甚至几天。一旦中途崩溃，若没有状态保存，所有进度都会归零。

不同框架的状态管理方案差异明显：
*   **LangGraph** 将状态建模为**类型化字典**（Type-Safe Dictionary），通过**归约器**（Reducer）合并状态更新。检查点在**超级步骤边界**（Superstep Boundaries）触发，支持中断后无缝恢复，甚至能实现时光倒流式的调试。
*   **OpenAI** 提供了四种互斥的**状态策略**（Stateful Strategies）：分别是应用内存、SDK 会话、服务器端对话 API，以及轻量级的 `previous_response_id` 链式调用，从而适配不同的部署场景。
*   **Claude Code** 的设计则极具特色：用 **Git 提交**（Git Commits）作为检查点，用**进度文件**（Progress Files）作为结构化草稿本，借助 Git 的版本控制能力，实现任务进度的精准回溯与管理。

#### 8. 错误处理（Error Handling）
它是智能体在复杂环境中稳定运行的安全网。很多人忽视了一个残酷的数学事实：一个 10 步的任务流程，即便每一步成功率高达 99%，端到端的总成功率也只有约 90.4%。错误会像滚雪球一样不断放大，最终导致任务彻底失败。

因此，生产级的 Harness 必须建立完善的错误分类与处理机制。LangGraph 的设计堪称行业典范，它将错误分为四类：
1.  **瞬时错误**（Transient Errors）：比如网络波动、 API 限流，采用带退避策略的重试机制。
2.  **模型可恢复错误**（Model-Recoverable Errors）：比如参数错误、逻辑失误，将错误包装成工具消息返回给模型，让模型自主调整。
3.  **用户可修复的错误**（User-Correctable Errors）：比如权限不足或者配置错误，通过中断流程等待人工输入。
4.  **意外错误**（Unexpected Errors）：比如系统崩溃或者底层异常，这种会直接抛出错误，便于调试。

Anthropic 的策略更侧重流程稳定性：在工具处理器内部捕获所有失败，将错误结果返回给模型，确保主编排循环不中断。Stripe 的生产级 Harness 则更为保守，将重试次数严格限制在两次以内，避免无限重试引发的资源耗尽。

#### 9. 护栏（Guardrails）
它是智能体的安全红线，防止智能体做出越权、有害、违规操作，是企业级应用的核心保障。

*   **OpenAI 的 SDK** 实现了三层防护体系：
    1.  第一层是**输入护栏**（Input Guardrails）：在智能体接收用户请求时运行，过滤恶意和违规输入。
    2.  第二层是**输出护栏**（Output Guardrails）：在最终输出前运行，确保输出内容合规安全。
    3.  第三层是**工具护栏**（Tool Guardrails）：每次调用工具时都运行，管控工具调用权限，防止高风险操作。
    一旦触发护栏的**绊线机制**（Tipping Mechanism），智能体会立即终止当前操作，实现紧急制动。

*   **Anthropic 的护栏设计**则更加彻底：在架构上将权限执行与模型推理完全解耦。模型只负责思考想做什么，工具系统负责判断能做什么，两者互不干扰。
*   **Claude Code** 可以独立管控大约 40 种离散的工具能力，分三个阶段严格把关，包括在项目加载时建立**信任体系**（Trust System），每次调用工具前检查权限，以及高风险操作必须获得用户的明确确认，从根源上杜绝安全风险。

#### 10. 验证与反馈（Verification & Feedback）
这是玩具级智能体和生产级智能体的分水岭。没有验证的智能体，输出结果永远不可信。

Anthropic 推荐了三种行业通用的验证方式：
1.  **基于规则的反馈**（Rule-based Feedback）：通过测试用例、Linter 代码检查，以及类型检查器等确定性工具，验证输出结果的准确性。
2.  **视觉反馈**（Visual Feedback）：借助 Playwright 等工具截图，检查 UI 任务或可视化操作的完成效果。
3.  **让模型当裁判**（Model-as-a-Judge）：用独立的子智能体评估主智能体的输出，从语义、逻辑和效果等维度给出反馈。

Claude Code 的创始人鲍里斯·切尔尼（Boris Cherny）明确指出，给智能体加入验证自身工作的机制，能让输出质量提升 2 到 3 倍。所以说，验证循环不是额外开销，而是保证智能体产出价值的必要投入。

#### 11. 子 Agent 编排（Subagent Orchestration）
它可以让单个智能体升级为智能体集群，从而解决复杂、大规模、多领域的任务需求。当任务涉及多个专业领域、工具数量过多、流程过于复杂时，单个智能体的性能会大幅下降，子 Agent 编排就是最优解。

目前的主流框架都有成熟的子 Agent 实现方案：
*   **Claude Code** 支持三种执行模式：
    *   **Fork 模式**：创建父上下文的精确副本。
    *   **Teammate 模式**：通过独立终端面板通信。
    *   **Worktree 模式**：为每个 Agent 分配独立 Git 工作树。
*   **OpenAI 的 SDK** 支持两种模式：
    *   **Agents-as-Tools**：让专家 Agent 处理细分任务。
    *   **Handoffs 模式**：实现任务全面交接。
*   **LangGraph** 则将子 Agent 实现为嵌套状态图，通过图结构管理任务流转。

#### 12. 初始化与环境搭建（Initialization & Environment Setup）
它是所有模块协同工作的起点，定义了智能体从启动到运行的完整生命周期。我们可以通过一个标准执行周期，来理清所有模块是如何联动的：

1.  **第一步，提示词组装**：Harness 整合系统提示、工具 Schema、记忆文件、对话历史、用户消息，构建一个完整的输入。
2.  **第二步，模型推理**：将组装好的提示词发送给模型，生成文本或工具调用输出。
3.  **第三步，输出分类**：判断是否需要工具调用、任务交接或直接输出答案。
4.  **第四步，工具执行**：校验参数、检查权限、沙箱运行，只读操作并发、写操作串行。
5.  **第五步，结果打包**：将工具执行结果和错误信息，格式化为模型的可读消息。
6.  **第六步，上下文更新**：将结果追加到对话历史，触发上下文压缩。
7.  **第七步，循环执行**：回到第一步重复流程，直到满足终止条件。

终止条件是多层级的，包括模型输出无工具调用、达到最大轮次、Token 预算耗尽、护栏触发、用户中断、安全拒绝等等。简单的任务 1-2 轮即可完成，复杂的重构任务可能需要几十轮循环、串联几十次工具调用，全靠初始化与环境搭建保证流程有序推进。

### 主流智能体框架对比与共同进化
拆解完十二大核心模块，我们再来看看全球主流智能体框架是如何落地 Agent Harness 的。它们的设计哲学、技术路径、适用场景有何差异？这对我们选择、搭建自己的智能体至关重要。

1.  **Anthropic Claude Agent SDK**：它是**薄 Harness**（Thin Harness）哲学的极致代表，核心是信任模型和简化框架。通过 `query()` 函数创建智能体循环，运行时是极简的**笨循环**（Dumb Loop），遵循从收集到执行，再到验证（Gather-Act-Verify）的流程。状态管理用 Git 提交，多智能体支持 Fork、Teammate、Worktree 三种模式。核心优势是轻量、高效、与模型深度耦合。

2.  **OpenAI Agents SDK**：采用**代码优先**设计理念，通过 `Runner` 类实现 Harness，支持异步、同步、流式三种运行模式。工作流用原生 Python 编写，无需学习专用图 DSL。状态管理提供四种策略，多智能体支持 Agents-as-Tools 与交接。侧重开发者友好、快速落地，适合快速开发生产级应用。

3.  **LangGraph**：从 LangChain 进化而来，采用图结构设计，将 Harness 建模为显式状态图，通过 `llm_call` 和 `tool_node` 两个节点和条件边来实现流程控制，支持嵌套状态图。侧重显式流程控制、可调试性，适合复杂、多分支的长流程任务。

4.  **CrewAI**：主打基于角色的多智能体架构，将智能体、任务、团队解耦，通过 Flows 层实现路由与验证。侧重多智能体协作、角色分工，适合团队式、多角色的复杂任务场景。

5.  **AutoGen**：现在已经演进为了微软智能体框架，开创了对话驱动编排的先河，支持顺序、并发、群组聊天、交接、magentic 五种编排模式。核心是将对话作为协作协议，适合开放式、多智能体交互的场景。

这五大框架，核心模式高度趋同，都围绕编排循环、工具、记忆、上下文等核心模块构建，但是设计哲学截然不同。没有绝对的优劣，只有场景的适配。

### Harness 与模型的共同进化规律
理解了 Harness 的模块与框架，我们再通过脚手架隐喻，来看看 Harness 与模型的共同进化规律，这也是未来 AI 架构的核心趋势。

我们常见的建筑上的脚手架，是临时基础设施，帮助工人完成施工，大楼建成后就会拆除。Agent Harness 也是如此，它是让模型落地为智能体的临时支撑。模型能力越强，Harness 的复杂度就应该越低。

行业实践已经验证了这一点：Manus 项目在半年内重构五次，每次都做减法，将复杂的工具定义简化为通用 Shell 执行，将管理智能体简化为结构化交接，性能反而持续提升。这背后正是**共同进化**（Co-evolution）原则。现代大模型在后训练阶段，会将特定 Harness 纳入训练循环，模型与框架深度耦合。模型内化的能力越多，Harness 需要的封装就越少。一个优秀的 Harness 设计，必须通过面向未来的测试，指的是模型升级后，智能体性能自然提升，无需增加 Harness 复杂度。未来的行业趋势，一定是更薄的 Harness、更强的模型、更模块化的架构。

### 七大架构抉择
最后，我们来总结搭建 Agent Harness 必须面对的七大架构抉择，这是所有 AI 工程师的核心考题：

1.  **单智能体 vs. 多智能体**：行业共识是先榨干单智能体性能。多智能体有额外开销，只有工具重叠超 10 个或者任务域明显分离的时候，才考虑拆分。
2.  **ReAct 循环 vs. 计划-执行循环**：ReAct 灵活但是每步成本高。而计划执行会分离规划与执行，LLMCompiler 数据显示比顺序 ReAct 快 3.6 倍。
3.  **上下文管理策略**：有五种方法，包括基于时间清理、对话摘要、观察掩码、结构化笔记、子智能体委派。核心是保留推理痕迹，减少 Token 消耗。
4.  **验证循环设计**：通过**计算式验证**（Computational Verification），比如测试、Linter 来提供确定性，以及用**推理验证**（Reasoning Verification），比如让模型做裁判来解决语义问题，两者结合最优。
5.  **权限与安全**：**宽松模式**（Loose Mode）高效但是有风险，**严格模式**（Strict Mode）安全但是低效，需要根据部署场景来平衡。
6.  **工具范围**：简单来说，工具越多性能越差。Vercel 砍掉 80% 的工具后性能反而提升。原则是只暴露当前步骤所需要的**最小工具集**（Minimal Toolset）。
7.  **Harness 的厚度**：**薄 Harness** 需要信任模型，**厚 Harness** 需要编码来控制逻辑。模型越强，越应该偏向薄 Harness。

回到我们最开始的问题：为什么有的智能体演示的时候十分流畅，生产环境却非常翻车呢？答案从来不是模型不行，而是 Harness 的架构可能不够完善。两个一模一样的模型，只因为 Harness 设计不同，性能可能就会天差地别。2026 年的 AI 竞争，也早已不是单纯模型参数的内卷了，还是 Harness 工程的较量。如何把上下文当稀缺资源管理，如何设计拦截错误的验证循环，如何构建无幻觉的记忆系统，如何平衡脚手架与模型的能力，这才是 AI 工程化的核心硬骨头。

下一次当你的智能体掉链子时，先别着急责怪模型，低头看看它的 Harness，也许问题大概率就出在这里。
感谢收看本期视频，我们下期再见。