这次我们来看一个搜索热度很高但多数文章都没讲透的主题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 核心能力速览能力项说明本质Agent 工程化基础设施 / 架构模式不是单一模型核心组成模型客户端、工具注册表、上下文管理、循环控制、可观测性解决的核心问题让 Agent 从“单次问答”变成“可运行、可调试、可接入业务系统”与 Agent 的区别Agent 是目标Harness 是承载 Agent 的执行系统硬件要求取决于接入的模型纯 API 模式几乎无 GPU 门槛本地模型需按模型量级评估启动方式脚本启动 / API 服务启动接口 API支持通常以 HTTP 接口暴露批量任务支持可按任务队列编排可观测性需要自行接入日志、耗时统计、异常追踪不属于模型能力适合场景客服问答、文档处理、代码生成、数据分析、自动化流程等要强调一点很多文章把“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 callHarness 进入工具执行阶段。先在工具注册表里找到对应函数再按参数结构调用函数。这里要注意超时控制外部工具可能挂起必须给工具执行设置超时时间。第 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_keyapi_key, base_urlbase_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