Harness Agent 架构模式解析：从原理到代码实现

这次我们来看一个搜索热度很高，但多数文章都没讲透的主题：Harness Agent。先给结论：Harness Agent 不是一个具体的大模型，也不是某个公司独家发布的固定工具，而是一种 Agent 工程化架构模式。你可以把它理解成大模型对外提供能力之前的“运行骨架”：模型负责推理，Harness 负责把工具调用、上下文管理、循环控制、可观测性和业务接口都串起来。2026 年这个方向上最典型的信号，就是“codex as a platform: build on the open agent harness”这类讨论成为热点——你可以在开放的 Agent Harness 上构建自己的平台，而不是每次从零写一套 Agent 调度逻辑。

很多人在搜索 Harness Agent 时，通常会一起搜 harness和agent区别、agent和harness各是什么意思，这说明大家第一个卡点不是代码，而是概念。这篇文章会从零开始讲清楚三件事：第一，Harness 和 Agent 到底是什么关系，为什么很多人把两者混在一起；第二，Harness 的底层运行原理和核心能力边界；第三，怎么用代码快速搭一个最小 Harness，并把它接到 API 服务和批量任务里。适合刚开始接触 Agent 开发的读者，也适合已经能跑通单轮模型调用、但不知道如何把模型标准化成“可用 Agent 服务”的人。全文用通用架构思路写，具体 SDK、模型名和接口路径需要按你实际使用的环境替换。

1. Harness Agent 核心能力速览

要强调一点：很多文章把“Harness Agent”写成某个可以直接下载的一键包，实际上更稳妥的判断是，它更接近一层抽象架构。你在网上看到的各种 Agent 框架，本质上都是在实现同一件事：把模型输出转成工具调用，再把工具结果还给模型继续推理。Harness Agent 的价值，就是把这套循环变成你项目里可维护、可替换的代码，而不是散落在一堆 Python 脚本里的临时逻辑。

2. 适用场景与使用边界

2.1 适合谁使用

Harness Agent 适合以下四类场景。

第一类是工具型 Agent 产品。比如内部知识库问答助手，用户问“帮我查一下昨天某个订单的状态”，Agent 需要先调用订单查询接口，拿到结果再整理成回复。这中间必须有一个 Harness 来管理对话历史和工具调度。

第二类是自动化流程编排。比如把一批 PDF 丢进来，每个文件先做 OCR、再做信息抽取、最后写入数据库。用 Harness 串起来以后，可以清晰看到每个任务走到哪一步、哪一步失败，方便加日志和重试。

第三类是代码生成与执行类场景。模型生成代码后，Harness 负责把代码放到沙箱环境运行、捕获报错、把报错信息反馈给模型继续修改。这样可以明显减少人工干预，也是目前 Agent 落地价值比较高的方向。

第四类是 API 化改造。团队里已经有成熟的模型调用代码，但每次都是脚本式运行，没法给前端或外部系统调用。通过 Harness 包一层 HTTP 服务，就能把 Agent 能力标准化，前端只关心提交问题和接收结果，不关心内部循环逻辑。

2.2 不适合什么场景

Harness Agent 不适合做纯单轮问答。如果业务只是“输入问题、输出答案”，不需要调用任何外部工具，那直接用模型 API 就够了，再包一层 Harness 反而增加延迟和复杂度。

它也不适合对延迟极其敏感的场景。因为 Agent 要多次调用模型，每加一轮工具调用就多一次模型往返，整体耗时可能比单次问答高一个数量级。如果业务要求 200 毫秒内返回，Harness 模式需要重新评估是否值得。

另外，如果团队没有完善的日志和监控体系，直接上复杂 Harness 会很难排查问题。Agent 的失败经常是“模型没按预期调用工具”“工具返回了脏数据”“循环没有收敛”，这些都需要观测手段来定位。没有日志，出了问题只能靠猜。

2.3 数据与合规边界

把大模型接入业务流程时，要先确认数据链路是否合规。涉及用户隐私、企业机密、版权素材的内容，不要直接传给外部模型服务；如果必须使用云端模型，需要确认服务协议是否允许这类数据进入。开源模型可以本地化部署，但要检查模型许可证是否允许商用场景。生成内容也要设置人工复核环节，避免模型输出错误或有害信息。凡是涉及肖像、声音、版权作品的处理，必须提前获得授权，并保留审批与溯源记录。

3. Harness 与 Agent 的底层区别

这部分是整篇文章的核心。每次搜索“harness和agent区别”的人都不少，区别其实可以浓缩成一句话：Agent 是“做什么”，Harness 是“怎么让 Agent 稳定地做”。

具体来说，Agent 指的是模型加提示词组合出的智能体，它能理解用户意图、决定下一步行动。Harness 则是包围在 Agent 外面的执行系统，它负责：

• 接收用户输入，组织 System Prompt 和对话历史；
• 把可用工具的描述转换成模型能理解的协议格式；
• 调用模型，解析模型返回的内容；
• 如果模型要求调用工具，执行对应工具函数；
• 把工具执行结果回传给模型，进入下一轮推理；
• 控制最大迭代次数，防止死循环；
• 记录每一轮输入、输出、耗时和 token 消耗。

用一个不精确但容易理解的类比：模型像发动机，Harness 像底盘、油门、方向盘和仪表盘。发动机决定了动力上限，但没有底盘和控制系统，发动机无法变成一个能上路的系统。把模型直接接到业务里，和把模型包进 Harness 再接入业务，差别就在这些基础设施。

也因此，“codex as a platform: build on the open agent harness”这句话才值得关注。它表达的是：模型层之外，Harness 层本身可以成为一个平台。你在 Harness 上接入不同的模型、不同的工具、不同的业务规则，就能快速搭出不同能力的 Agent，而不是每做一个业务都重新训练或重新包装一次模型。

4. 底层原理拆解：一个标准 Harness 的循环

一个标准 Harness 的运行过程，可以理解成一个带终止条件的循环。

第 1 步，构造初始消息列表。通常包含一条 System Prompt，告诉模型它的角色、能力边界、输出格式要求，再追加用户输入。

第 2 步，把工具清单传给模型。每个工具至少需要三个信息：唯一名称、功能描述、参数结构。模型不是直接执行函数，而是根据描述决定“我要调用哪个工具、传什么参数”，最终以结构化的 tool call 形式返回。

第 3 步，调用模型接口得到响应。如果模型返回的是普通文字内容，并且没有要求调用工具，Harness 就可以把结果作为最终答案返回给用户。

第 4 步，如果模型返回 tool call，Harness 进入工具执行阶段。先在工具注册表里找到对应函数，再按参数结构调用函数。这里要注意超时控制，外部工具可能挂起，必须给工具执行设置超时时间。

第 5 步，把工具执行结果作为一条 tool 消息追加到对话历史里，并带着更新后的历史再次调用模型。模型看到工具结果后，可能继续调用下一个工具，也可能直接给出最终答案。

第 6 步，重复第 3 到第 5 步，直到以下三种情况之一发生：模型给出最终答案；达到最大迭代次数；任务被外部中止。为了防止模型陷在工具调用里出不来，max_iterations 必须有默认值，比如 10 到 15 次。

这个循环是一切 Harness 的最小公倍数。无论框架用多复杂的抽象，底层都是这一个模式。理解它之后，再去读复杂框架的源码，也能看懂个七八成。

4.1 上下文管理怎么设计

上下文管理是 Harness 最容易出问题的部分。每一轮工具调用都会往历史里追加消息，10 轮之后上下文长度会膨胀得很厉害，尤其是工具返回结果本身就很长时，token 消耗会快速上升。

常用策略有三种。

第一种是滑动窗口截断。只保留最近的 N 条消息，最早的对话历史直接丢弃。适合对历史依赖不强的任务，实现最简单，但会丢失早期信息。

第二种是摘要压缩。当消息条数超过阈值时，调用模型把前面的历史总结成一段摘要，再用摘要替代原历史。适合需要长期记忆的任务，但会增加一次模型调用，延迟会变高。

第三种是结构化裁剪。工具调用结果通常只有“成功/失败、关键字段”重要，Harness 可以在写入历史前对工具结果做截断，比如只保留前 2000 个字符。对于超长工具响应，这是一种低成本高收益的优化。

在设计 Harness 时，最好一开始就把 Token 统计做成可观测指标。每个请求用了多少输入 token、多少输出 token、工具结果占了多少比例，这些数据会直接影响成本和性能优化。没有 token 统计，后面优化只能靠感觉。

4.2 工具注册表与错误处理

工具注册表建议用字典结构保存，以工具名称为 key。工具名称必须全局唯一，建议使用小写加下划线的命名方式，例如query_order、create_ticket。功能描述要写人话，模型依赖描述做选择，描述写得太模糊会导致工具调用准确率下降。

工具执行要处理三类异常：工具不存在、参数校验失败、工具运行时报错。理想情况下，Harness 应该把异常信息转成结构化的错误文本，作为工具执行结果返回给模型，让模型根据错误信息自行修正参数，而不是让整个 Agent 崩溃。例如参数错误时，返回“参数 xxx 缺失，请补齐后重试”，模型大概率会自动修正后再次调用。

5. 从零实现一个最小 Harness

下面用 Python 写一个教学用的最小 Harness。这不是某个框架的源码，而是一个演示 Agent 循环的模板，目的是把上一节的原理落到代码上。实际项目里可以用 OpenAI SDK、DeepSeek、本地 vLLM 等任何兼容接口，替换ModelClient的具体实现即可。

5.1 定义工具结构

# tool.py from dataclasses import dataclass from typing import Callable @dataclass class Tool: name: str description: str fn: Callable[..., str] def schema(self) -> dict: # 这里只做演示，真实项目建议用 pydantic 等方法生成 JSON Schema return { "type": "function", "function": { "name": self.name, "description": self.description, "parameters": {"type": "object", "properties": {}}, }, }

上面这段代码只定义了工具的基础字段。真实项目中，参数结构、必填字段、枚举约束都需要完整生成 JSON Schema，否则模型不知道怎么传参数。演示代码里省略参数描述，是为了保持可读性，实际使用不要这样偷懒。

5.2 封装模型客户端

# client.py from openai import OpenAI class ModelClient: def __init__(self, model: str, api_key: str, base_url: str): self.client = OpenAI(api_key=api_key, base_url=base_url) self.model = model def chat(self, messages: list[dict], tools: list[dict]) -> dict: kwargs = { "model": self.model, "messages": messages, } if tools: kwargs["tools"] = tools resp = self.client.chat.completions.create(**kwargs) message = resp.choices[0].message # 统一转成字典，方便 Harness 处理 return { "role": message.role, "content": message.content, "tool_calls": [ { "id": tc.id, "function": { "name": tc.function.name, "arguments": tc.function.arguments, } } for tc in (message.tool_calls or []) ], }

这个封装把不同模型 SDK 的返回结构统一成项目内标准结构，后续 Harness 就不用关心底层是哪个模型。需要注意：不同模型厂商的 tool call 字段可能存在差异，例如有的模型返回function.arguments是 JSON 字符串，有的直接返回对象。封装时要做兼容处理。

5.3 实现 Harness 主循环

# harness.py import json from tool import Tool from client import ModelClient class Harness: def __init__( self, model_client: ModelClient, tools: list[Tool], system_prompt: str, max_iterations: int = 10, ): self.client = model_client self.tools = {t.name: t for t in tools} self.system_prompt = system_prompt self.max_iterations = max_iterations self.messages = [{"role": "system", "content": system_prompt}] def execute_tool(self, tool_call: dict) -> str: name = tool_call["function"]["name"] arguments = json.loads(tool_call["function"]["arguments"] or "{}") tool = self.tools.get(name) if tool is None: return f"错误：工具 {name} 不存在" try: return str(tool.fn(**arguments)) except Exception as exc: return f"工具执行异常：{exc}" def run(self, user_input: str) -> str: self.messages.append({"role": "user", "content": user_input}) for _ in range(self.max_iterations): tools_schema = [t.schema() for t in self.tools.values()] response = self.client.chat(self.messages, tools_schema) assistant_msg = { "role": response["role"], "content": response["content"], } self.messages.append(assistant_msg) if not response.get("tool_calls"): return response["content"] or "模型未返回有效内容" for tool_call in response["tool_calls"]: tool_result = self.execute_tool(tool_call) self.messages.append({ "role": "tool", "tool_call_id": tool_call["id"], "content": tool_result, }) return "达到最大迭代次数，任务未完成"

注意这段代码中有一个比较关键的细节：assistant 消息里没有把tool_calls原样放进self.messages。在对接 OpenAI 兼容接口时，工具调用过程要求 assistant 的tool_calls字段和后续 tool 消息的tool_call_id一一对应，否则部分 SDK 会报错。实际实现时，需要把tool_calls一并追加到 assistant 消息中，再追加 tool 结果。这里为了缩短代码做了简化，以你实际使用的 SDK 校验规则为准。

5.4 跑通一个最小示例

# main.py from tool import Tool from client import ModelClient from harness import Harness def current_time() -> str: from datetime import datetime return datetime.now().strftime("%Y-%m-%d %H:%M:%S") def add(a: float, b: float) -> float: return