什么是 Agent Harness？Claude Code、DeepSeek Harness 和 Hermes Agent 背后的架构

实际上，这意味着模型、沙盒、会话存储、调度循环甚至 UI 主题都可以作为可替换的模块。该 harness 还附带一种“创建者模式”，用于检查运行中的系统、在内存中测试 Cordis 插件，并将它们组合成新的配置（DeepSeek）。

此处的赌注是：没有单一架构能够永远获胜，因此制胜之道在于把架构本身当作配置文件。

赌注二：少量固定机制，执行得当。

Claude Code 及其后续的 LangChain Deep Agents 采取了相反的赌注：挑选四种机制（规划、沙盒文件系统访问、子代理委派和上下文压缩），并投入精力使每一种机制都可靠。

列表中的每种机制都足够熟悉，以至于竞争对手会直接照搬：上表将 Claude Code 视为推广规划加子代理模式的功臣，而其他 harness 现在都在复制这一模式。该赌注之所以有效，是因为这四种机制在每项任务中都会一起运行。跳过其中一种，其他机制可以暂时顶替，直到一次长时间的使用暴露出缺口。

赌注三：能够产生复利的记忆。

Hermes Agent 认为目前最大的未解决问题是会话之间会发生什么。大多数 harness 在每次新对话时都会重置为空白上下文。Hermes 则提供了一种机制：在解决非平凡问题时，将其方法保存为可复用的技能。随后，在面对类似的未来请求时，它会先查看技能库，而不是从零开始推理，这样随着使用时间的增长，它在处理重复任务时会变得更快（Nous Research）。

这既是优势，也是风险：如果技能库无限制增长，可能会演变成超出其原始编写目的的技术债务。结合原生调度以及在 Telegram、Slack、Discord 等平台上的渠道集成，其设计目标更接近于常驻服务器上的助手，而不是你打开使用一次后就关闭的工具。

第四个赌注位于前三个赌注之下：Pi 和 Oh-My-Pi 认为其他 harness 构建的大部分功能是多余的负担，而四种工具加上一个扩展系统，对明确需求的工程师来说，胜过一个功能完整的平台。

Pi 的 GitHub Star 已突破 91,600，这一增长主要源于自然的口碑传播而非发布活动，表明该赌注具有持久力。

所有四种赌注都有其道理。它们针对不同的失效模式进行优化：DeepSeek Harness 针对架构锁定进行优化，Claude Code 和 Deep Agents 针对不可靠的长会话行为进行优化，Hermes 针对跨会话的重复工作进行优化，而 Pi 针对臃肿进行优化。

因此，在你做出选择之前，先问问自己今天哪种失效模式在占用你的时间。答案将帮助你选择合适的 agent harness。

在 60 行 Python 以内构建最小的 harness

下面的示例使用 Anthropic 的 Messages API 构建了图 1 中的五步循环：一个模型、三个工具，以及一个持续调用模型直至不再请求工具调用的循环。你将在这 60 行代码中看到本节讨论的所有失效模式。

import subprocess
from anthropic import Anthropic

client = Anthropic()

TOOLS = [
    {
        "name": "read_file",
        "description": "Read a UTF-8 text file from the working directory.",
        "input_schema": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
    {
        "name": "write_file",
        "description": "Write content to a file, overwriting it if it exists.",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string"},
                "content": {"type": "string"},
            },
            "required": ["path", "content"],
        },
    },
    {
        "name": "run_bash",
        "description": "Run a shell command inside the sandbox directory and return its output.",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
            "required": ["command"],
        },
    },
]

def execute_tool(name, tool_input):
    if name == "read_file":
        return open(tool_input["path"]).read()
    if name == "write_file":
        with open(tool_input["path"], "w") as f:
            f.write(tool_input["content"])
        return f"wrote {len(tool_input['content'])} bytes to {tool_input['path']}"
    if name == "run_bash":
        result = subprocess.run(
            tool_input["command"],
            shell=True,
            cwd="./sandbox",
            capture_output=True,
            text=True,
            timeout=30,
        )
        return result.stdout + result.stderr
    raise ValueError(f"unknown tool: {name}")

def run_harness(task, max_turns=15):
    messages = [{"role": "user", "content": task}]

    for _ in range(max_turns):
        response = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=4096,
            tools=TOOLS,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            return response.content[0].text

        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                output = execute_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": tool_results})

    return "stopped: hit max_turns without a final answer"

运行 run_harness("Write a Python script in sandbox/hello.py that prints the first 10 Fibonacci numbers, then run it and show me the output.") 并观察轮次如何展开：模型写入文件，调用 run_bash 执行它，读取输出，然后才产生最终的文本答案。上面表格中的每个生产 harness 都是此形状的更工程化版本。

Claude Code 在第一轮之前添加了一个规划步骤，并在每个 run_bash 等价操作之前添加了一个权限门。Deep Agents 添加了一个虚拟文件系统，以及一个中间件层，在 messages 超过模型上下文窗口之前对其进行压缩。DeepSeek Harness 使得 TOOLS 列表和模型客户端本身在运行时可互换。

这个玩具循环与严肃循环之间的差距完全体现在可靠性工程上：工具调用失败时会发生什么，第 50 轮会发生什么，以及什么阻止了沙箱触碰 ./sandbox 之外的任何东西。

execute_tool 中既不会捕获格式错误的响应，也不会捕获出错的工具，因此一次错误的工具调用可能会让模型反复陷入同一个错误结果的循环。您可以自行添加重试路径，否则 harness 默认会一直这样做。

此例中有两点值得更仔细地审视。首先，cwd="./sandbox" 是一个承载安全的边界：没有它，run_bash 可以执行宿主用户能执行的任何操作，这就是为什么每个严肃的 harness 都会在容器或受限目录中运行工具执行。这行代码在重构过程中很容易被意外删除，丢失它也很危险。

其次，max_turns=15 之所以存在，是因为这里没有任何东西告诉模型自行停止。如果您省略它，一个既没有轮次限制也没有成本限制的 harness 将会一直循环，并在模型不断请求工具的情况下持续消耗 token。如果您在重构过程中忘记了这一行，从外部看故障表现完全一样：一个永不返回的作业，以及一个会持续攀升的 token 账单，直到有人手动终止进程。

代理 Harness 解决方案栈

harness 不会单独运行。在几乎所有的生产代理部署中，会出现三个相邻的层次，了解每一层的起止位置，可以避免让 harness 去解决实际上属于上一层的问题。如果跳过这种映射，您将花费一周时间来调试 harness，而实际上错误在于沙箱中。

图 3：四个水平层，从底部到顶部堆叠。底层是协议层，即 Model Context Protocol（MCP）。这是一个共享标准，使得任何 harness 都能以相同的方式与任何外部工具或数据源通信。第二层是 harness 本身，即图 1 中的循环。

第三层是编排框架，位于单代理 harness 之上，负责协调多个代理或长期运行的有状态工作流：LangGraph、CrewAI、AG2、Mastra 和 DSPy 就位于此层。

最上层被绘制为两侧面板而非第四条横向带，是可观测性与沙箱：Langfuse、LangSmith 等工具会监视其下方的所有层，而 E2B 和 Modal 提供了 harness 沙箱运行的隔离执行环境。

协议层：MCP

Model Context Protocol 是一个开放标准，最初由 Anthropic 在 2024 年 11 月提出，用以以统一的方式将模型与外部工具、文件和数据源连接起来（Anthropic）。到 2025 年底，它已迁移至 Linux Foundation 下的 Agentic AI Foundation，获得 Anthropic、OpenAI 和 Block 的支持（Wikipedia）。

harness 通常会从 MCP 配置文件加载其工具列表，而不是从你手写的代码中读取：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/project"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

您在此添加的每个 MCP 服务器都会在 TOOLS 中以工具的形式可用，无需您编写任何新的 execute_tool 分支。编写一次集成，任何 MCP 兼容的 harness（如 Claude Code、Deep Agents、DeepSeek Harness 或您自己构建的）都可以使用它。这就是协议层的全部论点，一句话概括。

编排层

一个 harness 在单个循环中运行一个 agent。当您需要多个 agent 在具状态、长期运行的工作流中协作，并分配如规划者、研究者、审阅者等专门角色时，您就进入了编排框架的领域。在这里选择错误的框架会让您花费数月时间，而只需几行代码即可解决。

1. LangGraph 将多智能体工作流建模为带有检查点和时间旅行调试的图，并在受监管公司的有状态生产工作流中得到广泛应用（GitHub）

2. CrewAI 围绕按角色定义智能体并让它们在共享任务上协作而构建

3. AG2 是微软原始 AutoGen 项目的社区维护继承者，2026 年转向基于可组合中间件的异步事件驱动运行时（GitHub，pickaxe.co）

4. Mastra 是一个以 TypeScript 为先的智能体框架，在 2026 年 1 月达到 1.0 版本后，GitHub star 超过 22,000，每周 npm 下载量达 300,000（pickaxe.co，GitHub）

5. 来自 Stanford NLP 的 DSPy 将提示工程视为更接近编译而非手工撰写的过程，以度量为目标优化提示（GitHub）

可观测性与沙箱

当 agent 自行进行工具调用时，您需要看到它做了什么以及在哪里做的，以免盲目调试。Langfuse 和 LangSmith 会在整个会话中追踪每次模型调用、工具调用和 token 消耗，这就是您调试在第 34 轮失败的 harness 的方法（GitHub，LangChain）。

Braintrust 和 Arize Phoenix 在该追踪基础上添加了严格的评估，这样你就可以像测试代码库一样对 harness 的行为进行回归测试（Braintrust，Arize-ai/phoenix）。并且对于沙箱本身——即 run_bash-style 工具调用执行的隔离环境——E2B 和 Modal 提供可一次性使用的微型 VM，使得 harness 能够在不接触宿主机的情况下运行不可信代码（GitHub，Modal）。

为什么炒作曲线和采用曲线会分歧

图 4：两个 GitHub star 增长曲线在大约 400 天的时间内绘制在同一坐标轴上。DeepSeek Harness 曲线几乎是垂直的：从零开始保持平坦，然后在 2026 年 8 月 13 日发布后的前两天内几乎瞬间飙升至 95,000 多颗星星，随后趋于平缓。

Pi 曲线则呈相反形状：从其 2025 年 8 月发布开始，到一年后超过 91,600 颗星星，呈浅而稳定、几乎是直线的增长，过程中没有任何单一的峰值。两条曲线最终大约位于同一地点。

将这两条曲线放在同一张图表上的目的在于：到达该点的路径形状对每条曲线来说是不同的：一条曲线反映了协调的发布和恰时的公告；另一条曲线反映了一年来工程师们逐个决定该工具值得继续安装。

发布时的峰值表明项目引起了关注。持续使用则说明该工具在六个月后是否仍然在终端中打开，这两个问题有不同的原因。

DeepSeek Harness 在两天内获得的 95,000 颗星星是一个可验证的数字（Flowtivity），但它在很大程度上受到时机、分发以及众所周知的模型实验室现有受众的影响。

Pi 达到类似星星数量的增长传递了一种不同的信号：没有人为它在一年前协调发布。它通过尝试了四工具编码代理的工程师之间的口碑传播积累起来，他们继续使用它并告诉其他工程师。

如果仅依赖发布周峰值选择的工具，第一天可能看起来同样强大，但如果维护者转向下一个公告，三个月后可能仍会让团队陷入困境。这两个数字 ninguno 不能说哪个更重要，但如果你要选择一个 harness 来赌上团队的工作流程，应研究曲线的形状，而不仅仅是其当前高度。

陡峭的峰值随后出现平缓的尾部表明该项目正在形成活跃的社区，在将生产工作流提交之前值得关注。长而浅且未中断的攀升表明工程师们在热度消退后仍继续安装使用它，这是一个更强的（ albeit 较慢）信号。

如何为团队选择合适的 harness

将 harness 与你面前的失效模式匹配，而不是盲目跟随本周的热门趋势。依据星标而非你的瓶颈进行选择，这会导致团队后来花费数周进行迁移工作的错误。

• 如果你需要一个能够可靠地完成端到端单个编码任务的代理，想要获得最紧凑、最易审查的每次提交 diff 循环，可以从 Claude Code、Deep Agents 或 Aider 开始。这三者都很好地实现了图 1 中的规划加沙盒模式。

• 如果你担心供应商或架构锁定，并期望频繁更换模型：DeepSeek Harness 的插件一切设计以及 Deep Agents 的模型无关性都直接针对这一顾虑。这里若选择一个将某供应商的 SDK 硬编码到核心中的 harness，无论该供应商当前模型多么强大，都是错误的选择。

• 如果同一类任务在周或月之间反复出现，并且你希望代理通过积累已有知识随时间变得更快：Hermes Agent 的复合技能库正是为这种模式而构建，尤其是当你还希望它能够从团队日常使用的聊天平台访问时。

• 如果你希望审计表面积尽可能小，并且愿意自行编写缺失的扩展：Pi 的四工具核心，或者如果你特别需要 IDE 级别的工具、LSP 诊断和调试器，则可以选择 Oh-My-Pi——它们都建立在同一个最小基础之上。

• 如果你需要多个代理在长时间运行的有状态进程中协作：这个问题位于 harness 之上的一个层面。此时应升级到 LangGraph、CrewAI、AG2 或 Mastra。

无论你选择哪种方案，从第一天起都应将可观测性层视为必不可少。如果在无人值守运行的第 30 次轮次出现故障，没有任何追踪信息的 harness 将成为调试噩梦。若同时挂载 Langfuse 或 LangSmith，同样的故障只需五分钟即可修复。为省去下午的设置时间而跳过此步骤，首次出现代理在运行中途失败时，你将为此付出代价，且无人能说清原因。

无论选择哪种 harness，什么内容会被传承

本文中提到的具体工具名称在一年内可能会显得过时，因为该领域变化极快。长期有用的是图 1 中的五步循环、LangChain 在 Claude Code 架构中识别出的四种机制，以及图 3 中的分层堆栈。

接下来每月出现的任何新 harness，只要参照这三个参考点，你就能在一小时内判断它是否在结构上有真正的创新，还是仅仅在不同的插件系统下重新包装同样的循环，并伴随着更夸张的发布公告。

值得保留的技能是：读懂架构而不是读懂营销，这是这一类别无论如何工具名称更迭多快都无法让其过时的唯一要素。

结论

代理 harness 并不是一种神秘的新软件类别。它是运行时外壳，能够把模型的下一个 token 预测转化为能够规划、行动、检查自身工作并持续直至任务完成的代理。

harness 由五个部分构成，这些部分在每个实现中都会出现：循环、工具路由器、内存、规划以及沙盒边界。2026 年发生变化的只是规模。

足够多的团队交付了相互竞争的实现，以至于它们之间的架构差异值得研究。如今的格局从 DeepSeek 的插件一切内核和 Pi 的激进极简主义，到 Hermes Agent 的复合技能以及 Claude Code 和 Deep Agents 的四种固定机制。

上一节的数据印证了这一点：两天内获得 95,000 颗星，一年内获得 91,600 颗星，说明两条不同的路径指向了同一个结论。

亲自动手构建这个 60 行的版本。观察它如何循环。做完之后，市场上的每一个 harness 都不再看起来像魔法，而开始像是你可以根据其优势进行评估的工程决策。

接下来要探索的内容

• GitHub 上的 DeepSeek Harness: 阅读项目自述中关于 Cordis 插件架构的 README。

• LangChain 的 Deep Agents context-engineering 文档: 上文提到的自动压缩和卸载中间件在底层是如何工作的。

• 模型上下文协议规范: 本文中每个 harness 都可以插入的协议层。

• Hermes Agent 的技能文档: 复合技能库是如何被编写和复用的。

• LangGraph: 当单个代理不再足够时，这就是上一层。

• E2B: 为在宿主机外 sandbox 工具执行提供的具体起点。

访问我的 GitHub，探索我使用这个具备 AI 原生的工程流程构建并共享的 30+ 开源软件解决方案和开发者工具。