The following originally appeared on Hugo Bowne-Anderson’s Vanishing Gradients Substack and is being republished here with the author’s permission.本文最初发表于 Hugo Bowne-Anderson 的 Vanishing Gradients Substack，经作者许可在此转载。
The conversation around harness engineering is dominated by problems from coding and personal agents such as OpenClaw, but most agents are simpler. Builders should avoid over-engineering for capabilities that newer models may absorb anyway, the “Kirby effect,” and focus on durable fundamentals.关于智能体框架工程的讨论多集中在 OpenClaw 等编码和个人智能体所面临的问题上，但大多数智能体其实更简单。构建者应避免为了那些未来模型可能自动具备的功能而进行过度设计（即“柯比效应”），而应专注于持久的基础架构。
Statisticians sometimes use a deliberately crude question to show how a summary statistic can mislead: how many testicles does the average human have? The numerical answer may be defensible, but it describes almost nobody. Harness engineering has a similar problem. Ask, “What techniques do I need?” and the average answer becomes a long list: context management, memory, compaction, sub-agents, hooks, and orchestration. Few systems need all of it and the right harness depends on the job.统计学家有时会用一个刻意粗糙的问题来展示汇总统计数据是如何误导人的：人类平均有多少个睾丸？这个数值答案或许在数学上站得住脚，但它无法描述任何个体。框架工程也面临类似的问题。如果你问“我需要什么技术？”，得到的答案通常是一长串清单：上下文管理、记忆、压缩、子智能体、钩子（hooks）和编排。实际上，很少有系统需要全部这些功能，最合适的框架取决于具体的任务。
In this essay, you’ll learn:在本文中，你将了解到：
- What an agent harness is and how it differs from prompt and context engineering.什么是智能体框架，以及它与提示词工程（Prompt Engineering）和上下文工程（Context Engineering）的区别。
- How action complexity and context complexity determine the harness you need.操作复杂度和上下文复杂度如何决定你所需的框架。
- Why coding and deep-research agents require more context management than many support, sales, and enterprise agents.为什么编码和深度研究智能体比许多支持、销售和企业级智能体需要更多的上下文管理。
- How tools, state, routing, guardrails, traces, sub-agents, hooks, and human handoffs fit into the architecture.工具、状态、路由、护栏（guardrails）、追踪、子智能体、钩子和人工干预是如何融入架构的。
- Why harness features expire as models improve, and how to build the minimum viable harness for the job.为什么随着模型能力的提升，框架功能会逐渐失效，以及如何为任务构建最小可行性框架。
What is an agent?什么是智能体？
An AI agent in common parlance is an AI system that can do things: send emails, query databases, ping APIs, make appointments, write and execute code, and so on. AI engineers define them slightly differently: AI agents are LLMs with tools in a loop.在通俗语境下，AI 智能体是指能够执行任务的 AI 系统：发送邮件、查询数据库、调用 API、安排预约、编写并执行代码等。AI 工程师的定义则略有不同：智能体是处于循环中并拥有工具的 LLM（大语言模型）。
Consider what happens when you ask a coding agent to edit a file: it will first read the file, send the result back to the LLM, then edit it, then perhaps read it again, and so on, until the LLM “decides” it is finished and tells you.以要求编码智能体编辑文件为例：它会先读取文件，将结果返回给 LLM，然后进行编辑，接着可能再次读取，如此循环，直到 LLM“决定”任务完成并告知你。
This distinction is important because most common parlance agents don’t have such reasoning loops and are more aptly described as LLM workflows: take a sales workflow that这种区分很重要，因为大多数通俗意义上的智能体并没有这种推理循环，更准确地说是 LLM 工作流：以销售工作流为例，它会：
- Transcribes sales calls using a speech-to-text model;使用语音转文字模型转录销售通话；
- Extracts structured data from the transcript for the salesperson to verify;从转录文本中提取结构化数据供销售人员验证；
- Populates your CRM or database with the prospect’s information, next steps, and so on.将潜在客户信息、后续步骤等填充到 CRM 或数据库中。
This is an AI workflow: foundation models are used at each step, but for each sales call the workflow itself is deterministic. A call is transcribed, the relevant data is extracted, and the CRM is populated. When the next call happens, the workflow runs again as a separate task; no result is fed back to an earlier step, so there is no model-directed reasoning loop (any individual step could contain one, however, and agentic reasoning loops inside deterministic workflows are a common pattern).这是一个 AI 工作流：每一步都使用了基础模型，但对于每次销售通话，工作流本身是确定性的。通话被转录，提取相关数据，并填充到 CRM 中。当下一次通话发生时，工作流作为独立任务再次运行；没有结果被反馈到之前的步骤，因此不存在模型主导的推理循环（尽管单个步骤内部可能包含推理循环，但智能体推理循环在确定性工作流中是一种常见模式）。
All modern AI chat products, such as ChatGPT and Claude, however, are agentic: they have access to Web Search tools and image generation tools, for example, and will use them when deemed necessary. You interact with agents every day.然而，所有现代 AI 聊天产品（如 ChatGPT 和 Claude）都是智能体化的：它们可以访问网络搜索工具和图像生成工具，并在必要时使用它们。你每天都在与智能体互动。
What is an agent harness?什么是智能体框架？
If an LLM is the brain, you can think of the agent harness as the body. It includes all the tools and infrastructure the brain relies upon at runtime to get the job done.如果说 LLM 是大脑，那么智能体框架就是身体。它包含了大脑在运行时完成任务所依赖的所有工具和基础设施。
In practice, the harness handles five core jobs:在实践中，框架处理五项核心工作：
- Loop: Prompt the model, parse its response, execute its tool calls, and feed the results back.循环：提示模型、解析其响应、执行工具调用并将结果反馈。
- Tool execution: Run the commands, code, APIs, and other actions requested by the model.工具执行：运行模型请求的命令、代码、API 和其他操作。
- Context management: Decide which instructions, conversation history, files, and tool results enter each model call.上下文管理：决定哪些指令、对话历史、文件和工具结果进入每一次模型调用。
- State: Track the conversation, task progress, files touched, and anything that needs to persist across turns.状态：追踪对话、任务进度、涉及的文件以及任何需要在对话轮次间持久化的信息。
- Safety: Sandbox execution, require confirmation for sensitive actions, and block disallowed operations.安全：沙箱执行、敏感操作需确认、阻止违规操作。
Prompt engineering shapes an individual model call. Context engineering determines what the model sees. Harness engineering governs the complete system around those calls.提示词工程塑造单次模型调用。上下文工程决定模型看到什么。框架工程则管理这些调用周围的整个系统。
How complex does the harness need to be?框架需要多复杂？
One way to decide how much harness engineering a task requires is to separate two kinds of complexity:决定任务需要多少框架工程的一种方法是区分两种复杂性：
- Action complexity: How many tools, decisions, dependencies, and handoffs must the agent coordinate?操作复杂度：智能体需要协调多少工具、决策、依赖关系和交接？
- Context complexity: How much information must the agent gather, retain, and retrieve to complete the task?上下文复杂度：智能体需要收集、保留和检索多少信息才能完成任务？
The two can move independently. A support agent may complete a conversation in one turn while still routing across several tools and safety checks. A deep-research agent may receive only one user request while accumulating a large body of source material.这两者可以独立变化。一个支持智能体可能在单轮对话内完成任务，同时调用多个工具并进行安全检查。一个深度研究智能体可能只接收一个用户请求，却需要积累大量的源材料。
Harnesses for coding agents?编码智能体的框架？
The conversation around harness engineering has exploded recently and much of the focus is on context management, memory, compaction, tool offloading, and increasingly elaborate tools and techniques. If you’re building a coding agent (or using one!), it’s important to know about these. Generally, they’re important to consider when building agents that users tend to have long conversations with.关于框架工程的讨论最近呈爆发式增长，焦点多集中在上下文管理、记忆、压缩、工具卸载以及日益复杂的工具和技术上。如果你正在构建（或使用）编码智能体，了解这些很重要。通常，在构建用户会进行长期对话的智能体时，这些因素值得考虑。
The core can be surprisingly small, though: A coding agent can be built in 131 lines of Python, while a search agent using the same basic loop takes just 61. The tools change, but the underlying pattern doesn’t. A coding agent can even read its own tool definitions, write a new tool, hot-reload it, and use it on the next step. Capabilities can be added without permanently baking everything into the core harness.不过，核心部分其实可以非常小：编码智能体可以用 131 行 Python 代码构建，而使用相同基本循环的搜索智能体仅需 61 行。工具会变，但底层模式不变。编码智能体甚至可以读取自己的工具定义、编写新工具、热重载并将其用于下一步。无需将所有功能永久固化在核心框架中，即可扩展能力。
A stock coding agent can write code, but it doesn’t automatically understand your data, spot leakage, choose the right validation strategy, explain uncertainty, or connect a model to a business decision. In practice, users keep extending the harness around it: they add domain instructions to AGENTS.md, package recurring workflows as skills, and add tools, evals, and reproducibility checks. The shipped harness is only the starting point. It’s something builders actively work on. In a word, when using a coding agent, you are always actively involved in shaping and building your harness.现成的编码智能体可以编写代码，但它不会自动理解你的数据、发现泄漏、选择正确的验证策略、解释不确定性或将模型与业务决策联系起来。在实践中，用户不断在其周围扩展框架：添加 AGENTS.md 中的领域指令、将常用工作流封装为技能，并添加工具、评估和可重复性检查。交付的框架只是起点，它是构建者需要持续投入工作的对象。简而言之，使用编码智能体时，你始终在主动塑造和构建你的框架。
So what are common harness patterns for coding agents? Lance Martin (Anthropic, then at LangChain) identified 3 main context engineering patterns, which are fundamental for harness engineering:那么，编码智能体的常见框架模式有哪些？Lance Martin（曾就职于 Anthropic，后在 LangChain）确定了 3 种主要的上下文工程模式，它们是框架工程的基础：
- Reduce: Actively shrink the context passed to the model缩减（Reduce）：主动精简传递给模型的上下文。
- Offload: Move information and complexity out of the prompt.卸载（Offload）：将信息和复杂性从提示词中移出。
- Isolate: Use multi-agent architectures to delegate token-heavy sub-tasks.隔离（Isolate）：使用多智能体架构来委派消耗大量 Token 的子任务。
Then when conversations get longer than the context window of the LLM, you need to think through how to pass the necessary context to it: compaction used to be state of the art, then hand-off became prominent, and now compaction is back, due to the capabilities of more powerful models.当对话长度超过 LLM 的上下文窗口时，你需要考虑如何向其传递必要的上下文：压缩曾是前沿技术，随后交接（hand-off）变得流行，而现在由于更强大模型的能力，压缩技术又回到了主流。
Deep research is another case where context engineering matters. In a workshop with Ivan Leo, who previously built agents at Manus and is now at Google DeepMind, we built a deep research agent from scratch. The harness keeps research findings and task state available across many model calls. It generates a plan, gives search sub-agents separate queries and iteration budgets, runs them concurrently, then returns their findings to the main agent for synthesis and citation. The implementation also uses hooks, which let other parts of the system respond to events in the agent loop. A hook can render a tool call, log its result, or record a trace without putting that behavior inside the core loop. Deep research raises both action and context complexity: the agent must coordinate many searches while retaining enough evidence to produce a coherent, cited report.深度研究是另一个上下文工程至关重要的案例。在与曾任职于 Manus、现就职于 Google DeepMind 的 Ivan Leo 的研讨会上，我们从零开始构建了一个深度研究智能体。该框架在多次模型调用中保持研究发现和任务状态的可用性。它生成计划，为搜索子智能体分配独立的查询和迭代预算，并发运行它们，然后将结果返回给主智能体进行综合和引用。该实现还使用了钩子，允许系统的其他部分响应智能体循环中的事件。钩子可以在不将行为放入核心循环的情况下渲染工具调用、记录结果或保存追踪信息。深度研究增加了操作和上下文的复杂度：智能体必须协调多次搜索，同时保留足够的证据来生成连贯、有引用的报告。
When working with personal agents, such as OpenClaw or Hermes, managing context and memory is also important, particularly as the amount of information they create and have access to grows over time. Pi offers a useful baseline for coding-agent harnesses. It adds repository context through AGENTS.md, persistent sessions that users can resume or branch, and extensions for tools, skills, and prompts. OpenClaw builds on Pi and pushes the harness into personal-agent territory with an always-on daemon, chat interfaces, file-based memory, scheduled heartbeats and cron jobs, and tools for browsing, sub-agents, and device control. That additional infrastructure makes sense because the agent must persist and act over time, rather than complete one short task. Its memory system is deliberately plain: compaction summaries are appended to timestamped Markdown files, with no vector database or embeddings.在使用 OpenClaw 或 Hermes 等个人智能体时，管理上下文和记忆也很重要，特别是随着它们创建和访问的信息量随时间增长。Pi 为编码智能体框架提供了一个有用的基准。它通过 AGENTS.md 增加存储库上下文、提供用户可以恢复或分支的持久会话，以及工具、技能和提示词的扩展。OpenClaw 在 Pi 的基础上更进一步，通过常驻守护进程、聊天界面、基于文件的记忆、定时心跳和 cron 作业，以及用于浏览、子智能体和设备控制的工具，将框架推向了个人智能体领域。这种额外的基础设施是合理的，因为智能体必须长期存在并持续行动，而不是完成一个短任务。它的记忆系统非常简洁：压缩摘要被追加到带时间戳的 Markdown 文件中，不使用向量数据库或嵌入。
I do think these are all important and super interesting, but I want to help builders understand that most agents you’ll build don’t need any of them. But first: the Kirby effect and how frontier models are absorbing all of our agent harnesses.我认为这些都很重要且非常有趣，但我希望让构建者明白，你构建的大多数智能体根本不需要这些。但首先，让我们谈谈“柯比效应”以及前沿模型如何吸收我们所有的智能体框架。
The Kirby effect柯比效应
New model releases often force us to rebuild our harnesses. In fact, we often need to tear them out and rebuild them completely. If you don’t rip out your harness, it constrains the new model. As Nick Moy, an AI researcher at Google DeepMind who built the first multi-hop AI agent at Windsurf told me, “we should just unleash [the model], unfetter it, and let it flex its wings!”新模型的发布往往迫使我们重建框架。事实上，我们经常需要拆除旧框架并彻底重建。如果你不拆掉旧框架，它就会限制新模型。正如 Google DeepMind 的 AI 研究员 Nick Moy（他构建了 Windsurf 上的第一个多跳 AI 智能体）所言：“我们应该直接释放[模型]，解除束缚，让它展翅高飞！”
Manus has been re-architected five times in a year, LangChain’s Open Deep Research was rebuilt multiple times in a year to keep pace with model improvements, and even Anthropic rips out Claude Code’s agent harness as models improve (see here for more details). Why is this happening? Because the models are sucking up the harnesses around them.Manus 在一年内重构了五次，LangChain 的 Open Deep Research 为了跟上模型改进的步伐在一年内多次重建，甚至连 Anthropic 也会随着模型改进而拆除 Claude Code 的智能体框架（详情见此）。为什么会这样？因为模型正在“吞噬”它们周围的框架。
Remember chain-of-thought (CoT) prompting where we would see better performance from LLMs if we asked them to explain their reasoning? Well, it turns out that if you do reinforcement learning on CoT traces, you can build reasoning models! Plan mode followed the same path. AMP briefly shipped it as an experimental feature, then removed it when models could reliably obey “plan, but don’t edit.” As Nicolay Gerold (Amp Code) put it, “Having a separate mode for that, and having additional load on the user to remember, ‘Hey, I always have to go into plan mode,’ isn’t necessary anymore, because it’s just one simple instruction.” Claude Code still has it, though, as does Codex! In November 2025, the release of Opus 4.5 and GPT-5.2 signalled a step change in how capable coding agents had become. Simon Willison even wrote “It genuinely feels to me like GPT-5.2 and Opus 4.5 in November represent an inflection point”. Why was this possible then? The labs had been able to train their new models on enough of our agent traces, in particular using RLVR, that they were able to become far more accurate at tool calling, among other things.还记得思维链（CoT）提示词吗？当时我们发现如果要求 LLM 解释推理过程，性能会提升。结果证明，如果你对 CoT 轨迹进行强化学习，就能构建出推理模型！计划模式（Plan mode）也走了同样的路径。AMP 曾将其作为实验功能发布，随后在模型能可靠地执行“计划但不编辑”指令时将其移除。正如 Amp Code 的 Nicolay Gerold 所言：“为此设置一个单独的模式，并增加用户记住‘嘿，我总是必须进入计划模式’的负担，已经没必要了，因为它现在只是一条简单的指令。”不过，Claude Code 和 Codex 依然保留了它！2025 年 11 月，Opus 4.5 和 GPT-5.2 的发布标志着编码智能体能力的一次阶跃。Simon Willison 甚至写道：“对我来说，GPT-5.2 和 Opus 4.5 在 11 月的发布确实代表了一个转折点”。为什么当时能做到这一点？因为实验室已经能够利用足够多的智能体轨迹（特别是使用 RLVR）来训练新模型，使它们在工具调用等方面的准确性大幅提升。
Nicolay Gerold (Amp Code) calls this the Kirby effect: every component in a harness encodes an assumption about something the model cannot do on its own. As models improve, those assumptions expire, and the corresponding harness features can be removed.Nicolay Gerold（Amp Code）称之为柯比效应：框架中的每个组件都对模型自身无法完成的事情做出了假设。随着模型改进，这些假设会过期，相应的框架功能也可以被移除。
Harnesses for support agents支持型智能体的框架
Most AI builders will not be building coding agents or deep-research systems. They will be building support agents, sales agents, and enterprise agents that sit low on at least one of these dimensions. Many of these systems complete a task in one to five turns (time to resolution is key here!). Their harnesses still need careful tool design, structured outputs, routing, guardrails, traces, and handoffs, but they may need far less memory and compaction.大多数 AI 构建者不会去构建编码智能体或深度研究系统。他们将构建在上述维度中至少一个维度上处于较低水平的支持、销售和企业级智能体。这些系统中的许多在 1 到 5 轮内完成任务（解决时间是关键！）。它们的框架仍然需要精心的工具设计、结构化输出、路由、护栏、追踪和交接，但可能不需要太多的记忆和压缩功能。
William Horton (AI Engineer, Maven Clinic) and his team built Maven Assistant to help members navigate appointments, providers, support information, and women’s health content. When the agent first reached external users, every initial conversation was completed in a single turn. Compaction was rarely relevant, although one Zendesk retrieval returned far too much text. The architecture still contains several important harness components:Maven Clinic 的 AI 工程师 William Horton 和他的团队构建了 Maven Assistant，帮助会员处理预约、寻找医疗服务提供者、获取支持信息和女性健康内容。当智能体首次接触外部用户时，每场初始对话都在单轮内完成。压缩功能几乎不相关，尽管有一次 Zendesk 检索返回了过多的文本。该架构仍然包含几个重要的框架组件：
- Domain routing: A lead agent delegates requests to sub-agents for appointments, provider search, health content, and Maven support.领域路由：主智能体将请求委派给负责预约、提供者搜索、健康内容和 Maven 支持的子智能体。
- Bounded tool access: The system has roughly 15 to 20 tools distributed across those domains. Each sub-agent receives only the tools relevant to its job.受限的工具访问：系统在这些领域中分布了大约 15 到 20 个工具。每个子智能体只接收与其工作相关的工具。
- Tool interfaces designed for agents: Internal APIs are wrapped in safer interfaces. The application injects the user ID directly instead of asking the model to provide it.专为智能体设计的工具接口：内部 API 被封装在更安全的接口中。应用程序直接注入用户 ID，而不是要求模型提供它。
- Deterministic guardrails: Off-topic and prompt-hacking checks run before the main agent. When triggered, the system returns a fixed response without asking the LLM to improvise.确定性护栏：在主智能体之前运行离题和提示词攻击检查。当触发时，系统返回固定响应，无需 LLM 即兴发挥。
- Explicit human handoffs: Expressions of self-harm trigger an automatic transfer to support. Other transfers require the user to ask or confirm.明确的人工交接：自残表达会触发自动转接至支持人员。其他转接需要用户请求或确认。
- Controlled scope: The agent provides health information but does not diagnose. The team withheld high-cost benefits questions until the system could answer them reliably enough.受控范围：智能体提供健康信息但不进行诊断。团队在系统能够可靠回答之前，暂不提供高成本福利相关的问题。
Maven Assistant has low context complexity and moderate action complexity. Its harness work is concentrated in routing, tool design, guardrails, evaluation, and human handoffs rather than memory or compaction. But don’t forget about the Kirby effect. As these systems become more sophisticated, so will the models, and what you needed to engineer into your harness yesterday will be part of the model tomorrow.Maven Assistant 具有较低的上下文复杂度和中等的操作复杂度。其框架工作集中在路由、工具设计、护栏、评估和人工交接，而不是记忆或压缩。但别忘了柯比效应。随着这些系统变得越来越复杂，模型也会随之进步，昨天你需要辛苦构建到框架中的功能，明天可能就会成为模型内置的一部分。
The fundamentals will remain:基础将保持不变：
- Building LLM reasoning loops with tools, state, and control flow.构建带有工具、状态和控制流的 LLM 推理循环。
- Designing prompts and tool schemas.设计提示词和工具模式（schemas）。
- Managing context and memory.管理上下文和记忆。
- Using structured outputs, traces, and tool feedback to inspect and debug the loop.使用结构化输出、追踪和工具反馈来检查和调试循环。
- Applying guardrails and human handoffs.应用护栏和人工交接。
- Using Agent SDKs and MCP without outsourcing the system design.使用 Agent SDK 和 MCP，同时不外包系统设计。
- Running scheduled and event-driven work with hooks and cron jobs.使用钩子和 cron 作业运行定时和事件驱动的任务。
- Building evals that test task success, tool use, guardrails, and human handoffs.构建测试任务成功率、工具使用、护栏和人工交接的评估体系。
Evals also raise a boundary question. Vivek Trivedy’s account of the agent harness is runtime-oriented: it includes the tools, state, context, execution environment, orchestration, and control logic used while an agent completes a task. Hamel Husain has argued to me (in private correspondence) that the eval harness is part of the agent harness too. That extends the definition beyond runtime to include the infrastructure that runs test cases, captures traces and artifacts, and scores outcomes. We’ll discuss this, among other things, in an upcoming live conversation.评估也引出了边界问题。Vivek Trivedy 对智能体框架的描述是面向运行时的：它包括智能体完成任务时使用的工具、状态、上下文、执行环境、编排和控制逻辑。Hamel Husain 在私人通信中曾向我指出，评估框架也是智能体框架的一部分。这不仅将定义扩展到了运行时，还包括运行测试用例、捕获追踪和工件以及评分结果的基础设施。我们将在即将到来的直播对话中讨论这些内容。
When building agents, before reaching for compaction, memory, handoffs, or sub-agents, map the job on two axes: how many actions must the agent coordinate, and how much context must it carry across the task? If both are low, keep the harness small. Give the model the few tools it needs, test the loop, and add infrastructure only when a real failure demands it. Revisit those additions whenever a stronger model arrives, because yesterday’s necessary workaround may be tomorrow’s dead weight.在构建智能体时，在考虑压缩、记忆、交接或子智能体之前，先在两个轴上映射任务：智能体需要协调多少操作，以及在任务过程中需要携带多少上下文？如果两者都很低，请保持框架简单。给模型提供它所需的少量工具，测试循环，仅在真正出现故障时才添加基础设施。每当有更强的模型发布时，请重新审视这些添加项，因为昨天的必要权宜之计，明天可能会成为死重。
Want to go deeper? Check out our collection of agent-harness resources, including papers, talks, tools, and practical examples. I’m also running a four-hour workshop soon, Build AI Agents from First Principles, where we’ll build a working customer service agent from scratch and cover tools, state, context, memory, guardrails, SDKs, and MCP.想深入了解吗？请查看我们的智能体框架资源合集，包括论文、演讲、工具和实践案例。我很快还将举办一场四小时的研讨会“从第一性原理构建 AI 智能体”，我们将从零开始构建一个可用的客户服务智能体，并涵盖工具、状态、上下文、记忆、护栏、SDK 和 MCP。
