如何构建自定义 Agent Harness：把模型接入真实世界的脚手架

构建有用的 Agent，本质上是在做一件事：让模型在合适的时间拿到合适的上下文，并能安全、稳定地作用于真实环境。

模型本身很重要，但仅有模型并不等于一个可用的 Agent。真正让 Agent 能完成任务的，是围绕模型搭建的那层结构：它负责接入工具、管理上下文、维护状态、处理失败、执行策略，并在必要时把人类审批、记忆、文件系统或代码执行环境纳入循环。

这层结构可以称为 harness。如果把 Agent 拆开来看，可以用一个非常直接的公式理解：

agent = model + harness

模型负责推理和决策，harness 则负责把模型连接到真实世界。Agent 的实用程度，往往不只取决于模型有多强，还取决于这个 harness 是否适合当前任务。

Agent 循环与 Harness 的位置

一个基础 Agent 可以被理解为：模型在循环中调用工具，直到任务完成并返回结果。

Agent loop

在这个循环里，模型收到请求，观察当前上下文，决定是否调用工具，然后根据工具返回继续推理，最终产出结果。工具调用、观察结果、消息历史、系统提示词、执行环境、业务约束，都不是模型天然具备的能力，而是由 harness 持续提供。

因此，可以把 harness 理解为模型外部的任务运行环境。它把任务所需的记忆、工具、提示词、上下文、子任务、执行环境等能力组织起来，让模型不只是“回答问题”，而是能在真实任务中行动。

Model plus harness

这也引出两个关键判断：

Agent 的质量，很大程度取决于模型能否拿到正确上下文。
Harness 的职责，就是在每一步把正确上下文交给模型。

换句话说，构建 Agent 不是简单地把模型和工具绑定在一起，而是要设计一个能持续输送上下文、控制流程、隔离复杂度的运行框架。

使用 create_agent 搭建基础 Harness

在 LangChain 中，create_agent 是构建 harness 的基础原语。传入模型、工具和系统提示词后，就可以得到一个可运行的 Agent。

from langchain.agents import create_agent

agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=tools,
    system_prompt="you are a helpful assistant..."
)

这段代码体现的是 LangChain 对 Agent harness 的最小抽象：它实现核心 Agent 循环，同时把可定制部分暴露出来。

一些现成方案会提供预组装的 harness，例如 Deep Agents 或 Claude Agent SDK。它们通常内置较完整的中间件能力，包括记忆、上下文管理、沙箱等，可以帮助开发者更快搭建生产可用的 Agent。这类方案适合多数常见场景。

但并不是所有 Agent 都适合使用高度预设的结构。很多业务场景需要更细粒度的控制，例如：

定制系统提示词和上下文组织方式。
在工具调用前后加入业务逻辑。
根据任务复杂度切换模型。
在关键动作前加入审批或合规检查。
管理长期任务中的消息压缩、状态更新和失败重试。

create_agent 的定位正是保持足够轻量：它只提供核心循环，把扩展能力交给 middleware。这样，开发者既能从一个简单 Agent 开始，也能逐步叠加面向生产的能力。

Middleware：定制 Harness 的核心入口

Middleware 是 LangChain 定制 Agent harness 的关键机制。它可以挂接到 Agent 循环中的多个位置，例如模型调用前后、工具调用前后、Agent 启动和结束阶段。

Middleware hooks

这种设计的价值在于：每个 middleware 可以只负责一个关注点，同时又能和其他 middleware 自由组合。复杂 Agent 不必把所有逻辑塞进一个巨大的提示词或一个臃肿的工具注册函数里，而是把能力拆成可复用、可测试、可共享的模块。

Middleware 通常可以通过几类杠杆为 Agent 增加能力。

1. 确定性逻辑

并不是所有行为都适合交给提示词处理。业务规则、策略执行、动态控制、模型切换、消息历史更新、上下文压缩等逻辑，往往需要在 Agent 循环的特定位置稳定触发。

这类逻辑适合放在 middleware 中，而不是写进系统提示词。原因很简单：提示词只能影响模型倾向，middleware 才能保证流程真正执行。

2. 工具生命周期管理

工具并不总是静态列表。有些工具需要初始化，有些工具依赖外部资源，有些工具在运行结束后需要清理状态。

Middleware 可以负责工具的完整生命周期：初始化、注册、运行时控制和收尾。这样，工具配置和控制逻辑会自然聚合在一起，而不是散落在 Agent 定义的不同位置。

3. 自定义状态

很多 Agent 需要在一次运行中持续追踪状态。例如计数器、标志位、审批结果、临时缓存、任务进度等。

Middleware 可以扩展 Agent 状态，让不同 hook 之间共享数据。这样，一个 middleware 可以在模型调用前记录状态，在工具调用后更新状态，在 Agent 结束时再统一处理结果。

4. 流式输出处理

生产系统中的 Agent 输出通常不只面向一个消费者。UI 可能关心 token 增量，审计日志关心工具调用，监控系统关心延迟和错误。

Middleware 可以拦截并转换 Agent 的输出流，例如过滤事件、注入元数据、把不同事件路由给不同系统。对需要可观测性、审计和实时交互的 Agent 来说，这一层非常重要。

常见 Harness 能力与 Middleware 对应关系

一个生产级 Agent 通常会组合多种 middleware。具体需要哪些能力，取决于任务特征：任务是否长时间运行，动作是否敏感，是否需要执行环境，是否可能遇到工具或模型失败，是否需要人工审批。

能力	为什么重要	相关 middleware
防止上下文溢出	长会话会快速积累消息历史，如果不处理，可能超过上下文窗口。	`SummarizationMiddleware`、`ContextEditingMiddleware`
访问和更新记忆	在启动时加载相关知识，在运行结束后写回记忆，让 Agent 能从真实使用中持续改进。	`FilesystemMiddleware`、`MemoryMiddleware`、`SkillsMiddleware`
在环境中采取行动	固定工具集会限制 Agent 能力；文件系统和执行环境可以释放更灵活的解决方案。	`ShellToolMiddleware`、`FilesystemMiddleware`、`CodeInterpreterMiddleware`
委派任务	子 Agent 可以处理复杂子任务，并拥有干净的上下文窗口；待办列表可追踪长任务进度。	`SubAgentMiddleware`、`AsyncSubAgentMiddleware`、`TodoListMiddleware`
处理瞬时失败	模型和工具都可能不可预测地失败，生产系统需要重试、退避和兜底模型。	`ToolRetryMiddleware`、`ModelRetryMiddleware`、`ModelFallbackMiddleware`
执行策略	PII 处理、合规检查、审批门禁需要稳定执行，不能只依赖模型自觉遵守提示词。	`PIIMiddleware`、`HumanInTheLoopMiddleware`
控制 Agent 行为	并非所有场景都适合完全自治，关键动作前可以暂停并等待人类批准、拒绝或重定向。	`HumanInTheLoopMiddleware`
控制成本	Prompt 缓存可以降低长任务 token 成本，调用次数限制可以防止成本失控。	`ModelCallLimitMiddleware`、`ToolCallLimitMiddleware`、`PromptCachingMiddleware`

这些能力共同指向一个原则：harness 的任务不是让 Agent 看起来更复杂，而是让模型在正确位置获得必要支持。上下文、工具、状态、策略和执行环境越贴合任务，Agent 的表现越可靠。

什么是 Task-Harness Fit

可以用 task-harness fit 来描述 harness 与任务之间的匹配程度。

一个客服 Agent 所需的 harness，和一个长时间运行的编码 Agent 显然不同。前者可能更重视知识库上下文、用户身份、合规话术和审批策略；后者可能更需要文件系统、代码执行、任务拆解、上下文压缩和失败恢复。

因此，设计 Agent 时不应只问“该选哪个模型”，还要问：

任务需要什么上下文？
Agent 会遇到哪些失败？
哪些动作需要策略约束？
是否需要长期记忆？
是否需要文件系统、shell 或代码解释器？
是否需要把任务委派给子 Agent？
是否需要人工审批？
是否需要对成本、调用次数和上下文长度做控制？

这些问题的答案，决定了 harness 应该如何组合。

LangChain 提到，其 GTM agent、异步编码 Agent 和无代码 Agent builder 都建立在 create_agent 之上，并根据各自任务目标配置了不同的 middleware 栈。这说明，同一个基础 Agent 循环可以支撑多种形态的 Agent，关键在于外围 harness 如何贴合任务。

小结

Agent 不只是模型加工具。更准确地说，Agent 是模型与 harness 的组合。

模型提供推理能力，harness 负责把模型接入任务现场。它提供上下文、管理工具、维护状态、执行策略、处理失败，并把 Agent 的行为接入真实系统。

create_agent 的价值在于提供一个轻量核心：先给出基本 Agent 循环，再通过 middleware 扩展生产所需能力。对于需要细粒度定制的 Agent，这种方式比预设完整框架更灵活，也更容易把业务逻辑、工具生命周期、上下文管理和治理能力拆成可复用模块。

最终，优秀 Agent 的关键不只是选择一个能力强的模型，而是为任务设计一个足够贴合的 harness。