如果你正在做 AI 大模型应用开发或者刚刚把第一版 Agent 系统放进企业内部测试大概率会遇到这个场景演示的时候一切顺利一旦进入生产环境Agent 要么反复调用工具停不下来要么执行了一条高危命令没人拦得住要么多个 Agent 各说各话、日志乱成一团。问题出在哪很多时候并不是模型能力不够而是缺少了一个真正能把模型、工具、技能和安全边界统一管理起来的控制层。这个控制层在以 Codex CLI 为代表的第一方智能体工程中被称为 Harness也就是 Agent 的“缰绳”。围绕 Harness 的设计、实现、治理正在形成一门新的工程方向——Harness Engineering。我的判断是2026 年企业级 AI 大模型应用开发的竞争焦点正在从“谁的 Agent 更聪明”转向“谁的 Harness 更可靠”。不管你是正在给团队搭建 Multi-Agent 系统还是准备把 DeepSeek、GPT 等大模型能力接入业务系统都需要理解这套工程思路。这篇文章会先讲清楚 Harness、Multi-Agent、SandBox、Skill 四个概念的边界与关系然后手写一个最小可运行的 Harness 工程用它演示多 Agent 协作、沙箱隔离和技能注册的完整链路最后重点讨论企业落地时最容易被忽略的安全边界、可观测性和 Skill 版本治理问题。每个核心章节都有示例代码和排查建议建议收藏备用。1. 为什么 2026 年企业级大模型开发离不开 Harness Engineering1.1 从 Chatbot 到 Multi-Agent真正的变化不是“聊天”过去两年大部分企业做 AI 大模型应用是从聊天机器人开始的。一个对话接口、一个 Prompt、一个文档库就能做出一个能回答问题的小工具。但到了 2025 年下半年到 2026 年企业需求已经明显变化不再满足于“能说会道”而是要求 AI 真正动手做事。什么叫“动手做事”就是让大模型调用业务 API、写代码、操作数据库、生成报表、自动测试。当一个系统从“回答问题”变成“执行任务”时它就不再是一个聊天机器人而是一个 Agent 系统。当任务足够复杂一个 Agent 做不过来就需要多个 Agent 分工协作比如一个负责拆解需求、一个负责写代码、一个负责执行验证这就是 Multi-Agent 协同。这个变化看起来只是能力增强实际上带来了一整类新的工程问题Agent 怎么被约束工具调用怎么审批代码执行怎么隔离多个 Agent 之间的消息由谁转发一旦出错怎么回溯这些问题的答案统统不在模型本身而在模型之外的工程框架里。1.2 没有 Harness 时Agent 系统会出现的失控场景很多人第一次搭 Multi-Agent 系统时觉得只要把多个 Agent 串起来就算完成了。但实际运行一段时间后会遇到下面这些非常典型的场景第一个场景是无限循环。一个 Agent 调用工具后把结果返回给模型模型觉得信息不足继续调用工具然后再返回再调用。如果没有循环次数上限API 费用会在几分钟内冲到离谱的高度。第二个场景是权限失控。为了让 Agent 能力更强开发者在配置文件里给了它很高的执行权限结果 Agent 在一次任务中生成了删除命令系统毫不犹豫地执行了。这类事故在生产环境一旦发生代价极高。第三个场景是 Skill 冲突。团队里不同成员各自写了一些 Skill有人做数据分析有人做代码生成这些 Skill 都注册在同一个 Agent 上。遇到一个模糊任务时Agent 选错了 Skill导致结果完全不对。第四个场景是日志黑洞。多个 Agent 相互调用产生了大量中间日志。出了问题后开发者根本不知道是哪一步、哪一个 Agent、哪一个工具调用导致了失败只能凭感觉改配置。这些问题不是模型能解决的而是需要在模型外围建立一套统一的控制机制。这个机制就是 Harness。1.3 什么是 Harness Engineering给 Agent 装上缰绳和仪表盘Harness 这个词在英语里是“马具、缰绳”的意思。放在 AI 大模型开发语境下Harness 就是一套位于模型和实际工具、代码、数据之间的控制层。它决定了一个 Agent 什么时候可以调用工具、调用哪个工具、执行后的结果向谁反馈、出错时怎么熔断。Harness Engineering就是围绕这个控制层的设计、实现、测试和治理方法。它要解决的核心问题有三个第一编排。多个 Agent 之间如何协作、任务如何拆解、中间结果如何传递。第二约束。哪些工具能调用哪些命令能执行哪些操作需要审批哪些情况必须强行停止。第三可观测。每一步发生了什么模型输入了什么、工具返回了什么、耗时多少、消耗了多少 Token都要有清晰的记录。理解了这三个职责你就会明白Harness Engineering 不是某个具体产品的名字也不是一个只能靠购买平台才能获得的能力。它是一整套工程实践可以自己实现也可以基于现有的开源或商业框架去做。2026 年这项能力正在成为 AI 工程师的基本功。2. 核心概念Harness、Agent、Skill、SandBox 的区别与联系2.1 Harness 与 Agent马和缰绳的关系很多人容易把 Harness 和 Agent 混为一谈实际上它们是两个层次的东西。Agent 是一个主动执行任务的智能体它由大模型驱动能够理解用户请求、调用工具、生成结果。简单理解Agent 是“干活的马”。Harness 是包裹在 Agent 外围的控制框架。它定义了 Agent 在什么时候、以什么方式执行任务。尽管大模型本身拥有很强的推理能力但没有 Harness 的约束Agent 很容易失控。有一句判断在社区里流传很广Agent 决定“能做什么”Harness 决定“允许做什么”。这句话基本概括了两者的关系。Codex Harness、DeepSeek Harness 这类命名其实都是在强调官方或社区为特定智能体构建的控制框架而不是模型本身。2.2 Skill可复用、可治理的技能包再来看 Skill。在 Agent 开发中简单工具可以靠 Function Call 实现也就是让大模型在对话中主动调用一个已声明的函数。但到了企业级项目里越来越多团队开始使用 Skill 来管理更复杂的能力。Skill 本质上是一个可插拔、可复用、可版本管理的技能包。一个 Skill 通常会包含一段清晰的能力描述告诉模型这个技能是做什么用的一个或多个实体文件例如 Python 脚本、CLI 命令模板、API 调用规则可选的入参说明和使用示例。与 Function Call 相比Skill 最大的优点在于它像软件工程里的“模块”一样有明确的边界、描述和版本。团队可以像维护代码库一样维护技能库而不是把几十个函数散落在 Prompt 里。很多社区热词提到的“Skill 脚本”“Skill 插件”本质上就是在做这件事把某个具体能力封装成一个可以随时安装、加载、卸下的技能包。2.3 SandBox让 Agent 的错误停留在可控区域内当 Agent 开始实际执行代码或命令时必须有一道隔离墙这道墙就是 SandBox即沙箱。沙箱的核心作用是即使 Agent 生成的代码有 bug、逻辑有危险甚至被恶意 Prompt 诱导它也无法直接操作系统文件、读取全部环境变量、访问内网服务。企业生产环境的 Agent 默认应该开启沙箱并且遵循最小权限原则。在社区讨论中经常有人纠结“set up default sandbox”还是“disabled no sandbox”。这里有一个很明确的建议任何涉及代码执行、命令调用的企业级 Agent 系统都不应该允许完全关闭沙箱。开发调试时可以放宽限制但生产环境的默认配置必须严格。2.4 Multi-Agent 编排模式流水线、编排者、黑板Multi-Agent 不是简单地把多个 Agent 堆在一起。目前常见的编排模式有三种。流水线模式是最容易理解的任务按顺序经过多个 Agent上游的输出是下游的输入。例如一个 Agent 负责解析需求另一个 Agent 负责生成代码第三个 Agent 负责测试。编排者模式是最多企业采用的有一个主控 Agent 负责拆解任务并把子任务分发给不同的执行 Agent执行完的结果再汇总回主控。这种模式的好处是主控 Agent 可以看到全局能够动态调整策略。黑板模式则是多个 Agent 共享一块公共信息区域各自读取、写入、更新状态。适合用于任务状态频繁变化、角色之间信息高度共享的场景。无论采用哪种模式Multi-Agent 的协作逻辑都应该由 Harness 统一管控否则就会出现节 1.2 中提到的消息混乱和日志黑洞问题。下面用一张表来对比这四个概念概念解决的问题通俗类比典型落地方式Harness控制 Agent 的执行边界与协作流程缰绳、驾驶舱生命周期钩子、策略引擎、审计模块Agent执行任务具备推理和工具调用能力干活的人大模型 Prompt 工具调用循环Skill复用和治理 Agent 的具体能力插件、技能包注册表、脚本、API 封装SandBox隔离执行风险控制越权行为隔离舱容器、虚拟机、受限子进程3. 企业级 Multi-Agent 协同架构设计与 Harness 的职责边界3.1 一个典型的企业级 Agent 系统分层架构从架构角度看一个成熟的企业级 Multi-Agent 系统通常分为五层。交互层负责和用户对接处理自然语言输入并返回结果通常表现为 Web 页面、IM 机器人或 API 网关。Harness 控制层是整个架构里最关键的一层。它不直接产生业务结果而是负责把用户请求转换为受控的任务执行流程。权限校验、沙箱检查、Agent 调度、日志记录都发生在这里。Agent 编排层包含具体的 Agent 实例。每个 Agent 负责特定角色例如需求分析 Agent、代码生成 Agent、测试 Agent。它们接收 Harness 分发的任务后通过自己的模型推理循环完成任务。Skill 与工具层是所有具体能力所在包括已注册的各个 Skill、业务 API、基础工具、模型调用客户端。沙箱与基础设施层提供代码执行环境、数据存储、网络策略、监控采集等底层能力。这种分层的好处在于每一层都有明确的职责和边界。模型再强大也只是 Agent 编排层中的一个组件工具再丰富也需要经过 Harness 控制层的调度和审批。3.2 一次真实任务在架构中的流转路径我们以“帮用户写一个函数并验证运行结果”这个任务为例看一次完整的请求如何流转。用户输入请求后交互层先做基本校验把翻译成内部格式再交给 Harness。Harness 对请求做安全扫描确认没有越权风险后把任务派发给需求分析 Agent。需求分析 Agent 通过模型推理把用户请求拆解为任务清单。Harness 收到任务清单后把“生成代码”的任务分发给代码生成 Agent。代码生成 Agent 编写 Python 代码并返回。接着Harness 又把代码交给测试 Agent测试 Agent 的代码在沙箱中执行。最后沙箱的执行结果被回传Harness 汇总所有中间记录把最终结果返回给用户。整个过程中模型只负责理解和生成内容真正控制流程的是 Harness。这样做的好处是如果某一步出错可以精准定位如果想限制某个 Agent 的权限可以在 Harness 层直接配置如果想审计可以从日志里还原整条链路。3.3 Harness 的职责边界虽然 Harness 很关键但它不应该什么都做。经验法则是和模型推理强相关的事情交给 Agent和执行流程、权限、安全强相关的事情交给 Harness和具体业务强相关的事情交给 Skill 和工具层。如果 Harness 介入业务过深会导致框架层代码频繁变动维护成本迅速上升。反之如果 Agent 自己处理权限和沙箱每次推理都会增加不必要的上下文负担也更容易出现绕过校验的风险。这种边界意识是 Harness Engineering 入门时最重要的一课。4. 环境准备与项目初始化4.1 运行环境要求接下来进入实操部分。为了保证示例在不同环境下都能跑通本文只依赖 Python 标准库不引入第三方框架便于读者理解核心机制。推荐环境如下Python 3.10 或更高版本操作系统Windows、macOS、Linux 均可不需要 GPU示例使用模拟模型客户端不实际调用大模型 API文本编辑器或 IDE推荐使用 VS Code 或 PyCharm。如果你希望把示例中的模型客户端替换为真实企业模型服务再自行接入 OpenAI、DeepSeek 或其他兼容 API 对应的 SDK 即可。版本请以实际项目为准本文重点演示核心思路。4.2 项目目录结构建议先按下面的结构创建工程目录harness-demo/ ├── main.py └── harness/ ├── __init__.py ├── engine.py ├── sandbox.py ├── agents.py └── skills/ ├── __init__.py └── skill_registry.py目录划分说明main.py是程序入口负责组装各个组件harness/engine.py定义 Harness 控制层的基类harness/sandbox.py定义沙箱策略和执行器harness/agents.py定义多个不同角色的 Agentharness/skills/skill_registry.py定义技能注册表。4.3 初始化 Python 工程在harness-demo目录下打开终端创建并激活虚拟环境。cd harness-demo python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate然后确认 Python 版本python --version本文示例不依赖第三方包因此不需要执行 pip install 操作。5. 从零实现一个可用的 Harness 工程5.1 定义 Harness 生命周期钩子首先实现 Harness 控制层的基类。这个基类最重要的作用是定义 Agent 执行过程中的生命周期钩子让后续所有 Agent 都能在调用工具前做权限校验、在调用后做审计记录。文件路径harness/engine.pyHarnessEngine 是所有 Agent 控制器的基类。 它定义了 Agent 执行过程中最重要的几个生命周期钩子。 from abc import ABC, abstractmethod class HarnessEngine(ABC): def __init__(self, agent_name, model_client, skill_registry, sandbox_policy): self.agent_name agent_name self.model_client model_client self.skill_registry skill_registry self.sandbox_policy sandbox_policy def before_tool_call(self, tool_name, tool_args): 工具调用前执行可以校验权限、改写参数、做审计。 if not self.sandbox_policy.is_allowed(tool_name, tool_args): raise PermissionError(fSandbox 拦截了工具调用: {tool_name}) def after_tool_call(self, tool_name, tool_args, result): 工具调用后执行可以记录结果、触发后续动作。 self.sandbox_policy.audit(tool_name, tool_args, result) def run(self, user_request): 主执行流程子类需要实现具体的决策循环。 self.on_start(user_request) final_result self.execute_loop(user_request) self.on_end(user_request, final_result) return final_result def on_start(self, user_request): print(f[Harness] {self.agent_name} 开始处理请求) def on_end(self, user_request, result): print(f[Harness] {self.agent_name} 处理结束) abstractmethod def execute_loop(self, user_request): raise NotImplementedError这里真正值得关注的是before_tool_call和after_tool_call两个钩子。它们意味着你可以把任何安全策略、审计逻辑、日志逻辑集中放在统一位置而不是散落在每个 Agent 里。这样做才能保证后续所有 Agent 都遵循相同的规范。另外run方法把请求执行和生命周期管理拆分开子类只负责实现决策循环不必关心统一的前置校验和后置记录。这种“模板方法”设计是 Harness 工程里最常见的代码结构。5.2 实现技能注册表 SkillRegistry接下来实现技能注册表。它的作用是统一管理所有可被 Agent 调用的 Skill提供注册、查询、自动发现三种能力。这里的自动发现功能会让你后续增加新技能时不需要修改过多代码只需把技能包放到指定目录即可。文件路径harness/skills/skill_registry.py技能注册表统一管理所有可被 Agent 调用的技能。 import importlib import pkgutil class SkillRegistry: def __init__(self): self._skills {} def register(self, skill_name, skill_entry, description): 手动注册一个技能。 :param skill_name: 技能名称 :param skill_entry: 可调用对象通常是函数 :param description: 技能描述供模型选择时参考 self._skills[skill_name] { entry: skill_entry, description: description, } def get(self, skill_name): 根据名称获取技能入口。 skill self._skills.get(skill_name) if skill is None: raise KeyError(f未注册的技能: {skill_name}) return skill[entry] def list_skills(self): 返回所有技能的名称和描述。 return [ {name: name, description: meta[description]} for name, meta in self._skills.items() ] def auto_discover(self, package_name): 自动扫描指定包下的技能模块。 约定每个技能模块必须暴露 SKILL_DESC 和 run 函数。 这种约定式设计可以降低团队新增技能时的理解成本。 package importlib.import_module(package_name) for module_info in pkgutil.iter_modules(package.__path__): module importlib.import_module(f{package_name}.{module_info.name}) self.register( skill_namemodule_info.name, skill_entrymodule.run, descriptionmodule.SKILL_DESC if hasattr(module, SKILL_DESC) else 无描述, )这里有一个很好的团队协作约定所有 Skill 模块必须暴露SKILL_DESC和run。这意味着团队写新技能时不需要理解复杂的框架代码只要照着这个约定写一个模块就能被 Harness 自动发现并纳入管理。描述信息中的SKILL_DESC在真实项目中非常重要因为大模型正是依靠这些描述来决定什么时候调用哪个 Skill。5.3 实现沙箱策略与执行器现在实现沙箱策略与执行器。这部分是企业级安全的核心所在。文件路径harness/sandbox.py沙箱策略隔离 Agent 执行的代码与系统。 这个实现是一个参考模型。在企业环境中 应接入容器、虚拟机或云厂商的隔离沙箱服务。 import subprocess import tempfile import os class SandboxPolicy: def __init__(self, allow_networkFalse, allowlist_commandsNone, max_exec_time_sec30): self.allow_network allow_network self.allowlist_commands allowlist_commands or [python3, ls, pwd] self.max_exec_time_sec max_exec_time_sec self.audit_log [] def is_allowed(self, tool_name, tool_args): 根据工具名称和参数判断是否允许执行。 if tool_name execute_command: command tool_args.get(command, ) parts command.split() base parts[0] if parts else return base in self.allowlist_commands if tool_name http_request and not self.allow_network: return False return True def audit(self, tool_name, tool_args, result): 记录审计日志便于事后回溯。 self.audit_log.append({ tool: tool_name, args: tool_args, result_preview: str(result)[:200], }) def execute_in_sandbox(self, code: str): 把代码写入临时目录并用受限子进程执行。 with tempfile.TemporaryDirectory() as tmp_dir: script_path os.path.join(tmp_dir, sandbox_script.py) with open(script_path, w, encodingutf-8) as f: f.write(code) try: result subprocess.run( [python3, script_path], capture_outputTrue, textTrue, timeoutself.max_exec_time_sec, checkFalse, ) return { stdout: result.stdout, stderr: result.stderr, returncode: result.returncode, } except subprocess.TimeoutExpired: return { stdout: , stderr: f执行超时超过 {self.max_exec_time_sec} 秒, returncode: -1, }这段代码里的核心参数是allowlist_commands。它限制了 Agent 能够执行的命令范围。如果 Agent 收到的任务是执行某个不在白名单里的命令is_allowed会直接返回 FalseHarness 层的before_tool_call就会抛异常。这就构成了第一道防线即使大模型被恶意 Prompt 诱导最终能执行的命令也被限制在一个很小的范围内。第二道防线是max_exec_time_sec任何代码执行都有超时保护避免 Agent 陷入死循环。5.4 实现多 Agent 协作示例下面定义三个角色不同的 Agent需求分析 Agent、代码生成 Agent、测试 Agent。它们分别继承 HarnessEngine分别实现自己的execute_loop。关键之处在于它们共享同一个SandboxPolicy因此安全策略保持一致。文件路径harness/agents.py具体的 Agent 实现示例。 from harness.engine import HarnessEngine class RequirementAnalystAgent(HarnessEngine): 需求分析 Agent负责把用户需求拆解为任务清单。 def execute_loop(self, user_request): self.before_tool_call(llm_generate, {}) requirement_list self.model_client.chat( f你是需求分析师请把下面的需求拆解成可执行的任务清单{user_request} ) self.after_tool_call(llm_generate, {}, requirement_list) return requirement_list class CodeGeneratorAgent(HarnessEngine): 代码生成 Agent根据任务清单生成 Python 代码。 def __init__(self, agent_name, model_client, skill_registry, sandbox_policy): super().__init__(agent_name, model_client, skill_registry, sandbox_policy) self.code_blocks [] def execute_loop(self, requirement_list): generated_code self.model_client.chat( f请为以下需求生成 Python 代码只输出代码{requirement_list} ) self.code_blocks.append(generated_code) return generated_code class TestAgent(HarnessEngine): 测试 Agent在沙箱中执行生成的代码并给出测试结论。 def execute_loop(self, generated_code): sandbox_result self.sandbox_policy.execute_in_sandbox(generated_code) review self.model_client.chat( f代码执行结果如下请判断是否符合预期{sandbox_result} ) return { sandbox_result: sandbox_result, review: review, }可以看到Agent 的业务逻辑非常简单需求分析 Agent 只负责调用模型做文本拆解代码生成 Agent 只负责调用模型生成代码测试 Agent 只负责把代码丢进沙箱执行。每个 Agent 都没有权限自行决定是否绕过沙箱因为before_tool_call和after_tool_call已经在基类里统一强制生效。如果未来需要新增审计埋点只需要在基类中修改一处所有 Agent 都会生效。5.5 编写启动入口最后写启动入口把所有组件组装起来。我在示例中使用一个模拟的模型客户端这样不依赖真实大模型服务也能跑通全流程。你在实际项目中可以把fakeTrue替换为真实的大模型调用。文件路径main.py程序入口组装 Harness 控制层与多个 Agent。 from harness.engine import HarnessEngine from harness.sandbox import SandboxPolicy from harness.agents import RequirementAnalystAgent, CodeGeneratorAgent, TestAgent from harness.skills.skill_registry import SkillRegistry class LocalModelClient: 示例用模型客户端。 在企业项目中请替换为真实的大模型 API 或私有化部署服务。 def __init__(self, fakeTrue): self.fake fake def chat(self, prompt): if self.fake: return f[mock response for]: {prompt[:80]} # 真实实现接入企业实际的大模型服务 raise NotImplementedError(请接入企业实际的大模型服务) if __name__ __main__: skill_registry SkillRegistry() sandbox_policy SandboxPolicy(allow_networkFalse) model_client LocalModelClient(fakeTrue) analyst RequirementAnalystAgent( agent_name需求分析Agent, model_clientmodel_client, skill_registryskill_registry, sandbox_policysandbox_policy, ) coder CodeGeneratorAgent( agent_name代码生成Agent, model_clientmodel_client, skill_registryskill_registry, sandbox_policysandbox_policy, ) tester TestAgent( agent_name测试Agent, model_clientmodel_client, skill_registryskill_registry, sandbox_policysandbox_policy, ) user_request 写一个函数输入两个数字返回它们的最大公约数并演示运行结果 requirement_list analyst.run(user_request) generated_code coder.run(requirement_list) test_result tester.run(generated_code) print( 需求分析结果 ) print(requirement_list) print( 生成代码 ) print(generated_code) print( 沙箱执行结果 ) print(test_result)5.6 运行与验证执行下面的命令python main.py预期输出中会出现三个 Agent 的处理日志以及“需求分析结果”“生成代码”“沙箱执行结果”三块内容。哪怕模型客户端是 mock 的你也应该能够看到整条 Multi-Agent 链路是完整走通的。如果某个 Agent 报错可以先检查是否是before_tool_call中沙箱策略拦截了不合规的调用。示例中所有 Agent 只调用了llm_generate而is_allowed对不认识的工具默认返回 True因此不会被拦截。真实项目中你要把is_allowed改成默认拒绝、只放行白名单中的工具这样才符合最小权限原则。6. 验证一个 Harness 是否“可用”的检查清单代码跑通只是第一步。在企业级项目中我们需要一套更严格的验证标准。下面这份检查清单可以用来评估你搭出来的 Harness 是否真正可落地。第一项是权限校验是否生效。你可以构造一个恶意工具名或一段包含危险命令的请求看看 Harness 是否会在工具调用前直接拒绝。如果还是放行说明权限钩子没有真正接进所有 Agent 的执行路径。第二项是沙箱隔离是否有效。让测试 Agent 执行一段带有rm -rf命令的代码确认它不会影响宿主机环境。在示例代码中沙箱执行的是临时目录里的子进程即使失败也只影响临时目录不会扩散到外部真实环境。生产环境更应该使用容器级隔离。第三项是日志链路是否完整。从用户请求进入 Harness 到最终返回中间每一步的 Agent、工具、耗时、结果是否都能找到记录。缺少日志链路的话生产环境一旦出问题你连排查的入口都没有。第四项是失败恢复是否明确。当某个工具调用抛出异常、某个 Agent 超时、沙箱返回错误时系统有没有对应的降级策略。一个健壮的 Harness 应该支持告警、重试、跳过、中止等多种策略而不是默默吞掉异常。第五项是 Skill 注册是否可审计。技能库里有哪些技能、分别由谁维护、哪个版本在使用、变更历史是什么这些都要有记录。Skill 一旦多起来没有治理就会变得混乱。第六项是上下文长度和成本是否可控。Multi-Agent 每次交互都可能引入大量上下文要提前设计好 Token 使用上限和费用监控。在实际项目中这一步往往比功能开发更容易踩坑。7. 常见问题与排查思路在企业项目里Harness、Multi-Agent、SandBox 和 Skill 的配合并不总是一帆风顺。下面整理了一些高频问题和对应的排查思路。问题现象可能原因排查方式解决方案Agent 反复调用同一个工具停不下来缺少最大迭代次数限制查看 Harness 日志中工具调用次数在 Harness 层增加循环次数上限沙箱模式下网络请求失败沙箱默认关闭网络访问查看沙箱策略配置按需开启白名单域名而不是全局放行生成的代码被沙箱拒绝执行代码里包含非白名单命令查看is_allowed返回的异常信息隔离或规范化代码生成 Prompt多个 Agent 之间日志混乱缺少统一 Trace ID检查 Harness 日志是否带请求 ID在请求入口生成 Trace ID 并贯穿所有日志新 Skill 无法被模型选中Skill 描述写得不够清晰打印 Skill 列表检查描述信息补充使用场景、示例和入参说明生产环境偶发超时外部 API 不稳定或超时设置过短查看模型调用耗时和重试记录增加超时退避重试策略沙箱被完全关闭系统风险升高配置项被误改成 disabled no sandbox检查配置中心和审计记录禁止生产环境关闭沙箱单独说一下最常见的循环问题。很多团队第一次跑 Multi-Agent 时都会遇到“Agent 停不下来”。解决方案很简单在 Harness 控制层维护一个计数器每次执行循环加一超过阈值就强制终止并返回当前已经完成的中间结果。这种策略并不复杂但必须在框架层实现不能指望每个 Agent 自己控制。关于 “Skill 不被模型选中” 的问题我的建议是把描述写得像“给同事的功能说明”一样具体包含触发场景、示例输入、输出结构。模型本质上是通过描述去匹配任务描述越模糊误选概率越高。8. 企业落地 Harness Engineering 的最佳实践8.1 安全边界最小权限是默认原则企业级 Agent 系统最容易踩的坑就是开发时为了方便把权限全部放开。等系统上线后一次工具调用错误就可能造成无法挽回的损失。最佳实践是所有权限默认关闭按需开放。具体包括命令白名单只包含业务必需的命令网络访问默认关闭只开放必要域名Skills 和工具尽量提供最小化、不可变参数所有涉及删除、写入生产数据的操作必须走审批流程。安全边界不是开发完成后补上去的而是要从 Harness 基类设计时就开始强制实现。8.2 可观测性没有日志就没有复盘机会在生产环境里一个 Multi-Agent 系统的调试难度远高于单体服务。因为每个 Agent 都有一次模型调用和至少一次工具调用请求链路天然较长。建议在 Harness 层统一埋点为每次请求生成唯一 Trace ID并记录以下关键信息Agent 名称和版本输入输出摘要模型名称、Token 消耗、耗时工具名称、参数、返回结果、返回码沙箱执行结果或错误信息。有了这些数据你可以快速定位影响整体结果的具体环节。8.3 Skill 治理所谓“自我进化”其实是一套版本纪律热词里经常提到“自我进化的 Skill”这里给出一个工程化的理性理解Skill 的进化不是模型自己悄悄修改自身权重而是指技能库的迭代闭环。当某个 Agent 在运行过程中发现一种更高效的用法团队可以把这种用法固化成一个新的 Skill或者更新已有 Skill 的描述和逻辑。经过沙箱验证和人工评审后新版本替换旧版本旧的归档保存。这本质上是一套版本治理体系。一个企业级的 Skill 仓库应当有明确的命名规范、版本号、作者、变更记录和测试用例。这样技能库才能像代码库一样健康迭代而不是越用越乱。8.4 生产环境变更备份、灰度、回滚缺一不可如果 Harness 配置或 Skill 变更要部署到生产环境务必先在测试环境验证。按照以下节奏执行对当前配置和知识库做完整备份灰度发布到小流量环境观察日志和成功率确认稳定后再全量发布如果出现异常立即回滚到上一个稳定版本。另外涉及数据库写入或删除操作时必须先经过备案和审批并在测试环境用脱敏数据完整验证避免生产误操作。8.5 团队协作统一约定比框架选型更重要最后想强调一点Harness Engineering 本质上是一项团队工程。无论你最终选择基于开源项目封装还是完全自研都比不上团队内部达成一套统一约定更重要。举例来说每个 Skill 模块必须暴露哪些字段、每个 Agent 必须实现哪个生命周期方法、每类日志必须包含哪些内容这些约定一旦定下来后续的维护成本会大幅下降。建议团队内部形成一份简短的开发规范文档把命名、注册、日志、安全、版本这五件事写清楚。往往这份文档的价值会超过某一次技术选型。9. 下一步怎么学Harness Engineering 不是只靠读文章就能掌握的技能真正有效的方法是在小项目里亲手把框架搭一遍。你可以从这个示例出发完成以下三步练习。第一步把示例中的LocalModelClient替换为真实大模型调用让它从 mock 输出变成真实推理观察全链路是否仍然稳定。第二步新增一个数据分析 Skill 并注册到SkillRegistry让测试 Agent 在沙箱中调用这个技能理解“技能注册 — 模型选择 — 沙箱执行”的完整链路。第三步设计一个真实的内部场景例如“自动整理周报并发送给团队成员”把流程拆解为多个 Agent 角色并在 Harness 层加上权限和日志。当你把这些练习做完再回头看 Codex Harness、DeepSeek Harness 以及其他社区方案时你会更清楚它们的设计意图也更有能力判断哪些功能可以直接使用、哪些需要自己扩展。2026 年的企业级 AI 大模型应用拼的不是模型的单一智商而是整个 Harness 体系能否把模型装进一条可控、可靠、可回溯的生产链路里。早一步把这个框架搭好你的团队就多一分从 Demo 走向生产的底气。
Harness Engineering：为 AI Agent 装上缰绳的企业级控制层
如果你正在做 AI 大模型应用开发或者刚刚把第一版 Agent 系统放进企业内部测试大概率会遇到这个场景演示的时候一切顺利一旦进入生产环境Agent 要么反复调用工具停不下来要么执行了一条高危命令没人拦得住要么多个 Agent 各说各话、日志乱成一团。问题出在哪很多时候并不是模型能力不够而是缺少了一个真正能把模型、工具、技能和安全边界统一管理起来的控制层。这个控制层在以 Codex CLI 为代表的第一方智能体工程中被称为 Harness也就是 Agent 的“缰绳”。围绕 Harness 的设计、实现、治理正在形成一门新的工程方向——Harness Engineering。我的判断是2026 年企业级 AI 大模型应用开发的竞争焦点正在从“谁的 Agent 更聪明”转向“谁的 Harness 更可靠”。不管你是正在给团队搭建 Multi-Agent 系统还是准备把 DeepSeek、GPT 等大模型能力接入业务系统都需要理解这套工程思路。这篇文章会先讲清楚 Harness、Multi-Agent、SandBox、Skill 四个概念的边界与关系然后手写一个最小可运行的 Harness 工程用它演示多 Agent 协作、沙箱隔离和技能注册的完整链路最后重点讨论企业落地时最容易被忽略的安全边界、可观测性和 Skill 版本治理问题。每个核心章节都有示例代码和排查建议建议收藏备用。1. 为什么 2026 年企业级大模型开发离不开 Harness Engineering1.1 从 Chatbot 到 Multi-Agent真正的变化不是“聊天”过去两年大部分企业做 AI 大模型应用是从聊天机器人开始的。一个对话接口、一个 Prompt、一个文档库就能做出一个能回答问题的小工具。但到了 2025 年下半年到 2026 年企业需求已经明显变化不再满足于“能说会道”而是要求 AI 真正动手做事。什么叫“动手做事”就是让大模型调用业务 API、写代码、操作数据库、生成报表、自动测试。当一个系统从“回答问题”变成“执行任务”时它就不再是一个聊天机器人而是一个 Agent 系统。当任务足够复杂一个 Agent 做不过来就需要多个 Agent 分工协作比如一个负责拆解需求、一个负责写代码、一个负责执行验证这就是 Multi-Agent 协同。这个变化看起来只是能力增强实际上带来了一整类新的工程问题Agent 怎么被约束工具调用怎么审批代码执行怎么隔离多个 Agent 之间的消息由谁转发一旦出错怎么回溯这些问题的答案统统不在模型本身而在模型之外的工程框架里。1.2 没有 Harness 时Agent 系统会出现的失控场景很多人第一次搭 Multi-Agent 系统时觉得只要把多个 Agent 串起来就算完成了。但实际运行一段时间后会遇到下面这些非常典型的场景第一个场景是无限循环。一个 Agent 调用工具后把结果返回给模型模型觉得信息不足继续调用工具然后再返回再调用。如果没有循环次数上限API 费用会在几分钟内冲到离谱的高度。第二个场景是权限失控。为了让 Agent 能力更强开发者在配置文件里给了它很高的执行权限结果 Agent 在一次任务中生成了删除命令系统毫不犹豫地执行了。这类事故在生产环境一旦发生代价极高。第三个场景是 Skill 冲突。团队里不同成员各自写了一些 Skill有人做数据分析有人做代码生成这些 Skill 都注册在同一个 Agent 上。遇到一个模糊任务时Agent 选错了 Skill导致结果完全不对。第四个场景是日志黑洞。多个 Agent 相互调用产生了大量中间日志。出了问题后开发者根本不知道是哪一步、哪一个 Agent、哪一个工具调用导致了失败只能凭感觉改配置。这些问题不是模型能解决的而是需要在模型外围建立一套统一的控制机制。这个机制就是 Harness。1.3 什么是 Harness Engineering给 Agent 装上缰绳和仪表盘Harness 这个词在英语里是“马具、缰绳”的意思。放在 AI 大模型开发语境下Harness 就是一套位于模型和实际工具、代码、数据之间的控制层。它决定了一个 Agent 什么时候可以调用工具、调用哪个工具、执行后的结果向谁反馈、出错时怎么熔断。Harness Engineering就是围绕这个控制层的设计、实现、测试和治理方法。它要解决的核心问题有三个第一编排。多个 Agent 之间如何协作、任务如何拆解、中间结果如何传递。第二约束。哪些工具能调用哪些命令能执行哪些操作需要审批哪些情况必须强行停止。第三可观测。每一步发生了什么模型输入了什么、工具返回了什么、耗时多少、消耗了多少 Token都要有清晰的记录。理解了这三个职责你就会明白Harness Engineering 不是某个具体产品的名字也不是一个只能靠购买平台才能获得的能力。它是一整套工程实践可以自己实现也可以基于现有的开源或商业框架去做。2026 年这项能力正在成为 AI 工程师的基本功。2. 核心概念Harness、Agent、Skill、SandBox 的区别与联系2.1 Harness 与 Agent马和缰绳的关系很多人容易把 Harness 和 Agent 混为一谈实际上它们是两个层次的东西。Agent 是一个主动执行任务的智能体它由大模型驱动能够理解用户请求、调用工具、生成结果。简单理解Agent 是“干活的马”。Harness 是包裹在 Agent 外围的控制框架。它定义了 Agent 在什么时候、以什么方式执行任务。尽管大模型本身拥有很强的推理能力但没有 Harness 的约束Agent 很容易失控。有一句判断在社区里流传很广Agent 决定“能做什么”Harness 决定“允许做什么”。这句话基本概括了两者的关系。Codex Harness、DeepSeek Harness 这类命名其实都是在强调官方或社区为特定智能体构建的控制框架而不是模型本身。2.2 Skill可复用、可治理的技能包再来看 Skill。在 Agent 开发中简单工具可以靠 Function Call 实现也就是让大模型在对话中主动调用一个已声明的函数。但到了企业级项目里越来越多团队开始使用 Skill 来管理更复杂的能力。Skill 本质上是一个可插拔、可复用、可版本管理的技能包。一个 Skill 通常会包含一段清晰的能力描述告诉模型这个技能是做什么用的一个或多个实体文件例如 Python 脚本、CLI 命令模板、API 调用规则可选的入参说明和使用示例。与 Function Call 相比Skill 最大的优点在于它像软件工程里的“模块”一样有明确的边界、描述和版本。团队可以像维护代码库一样维护技能库而不是把几十个函数散落在 Prompt 里。很多社区热词提到的“Skill 脚本”“Skill 插件”本质上就是在做这件事把某个具体能力封装成一个可以随时安装、加载、卸下的技能包。2.3 SandBox让 Agent 的错误停留在可控区域内当 Agent 开始实际执行代码或命令时必须有一道隔离墙这道墙就是 SandBox即沙箱。沙箱的核心作用是即使 Agent 生成的代码有 bug、逻辑有危险甚至被恶意 Prompt 诱导它也无法直接操作系统文件、读取全部环境变量、访问内网服务。企业生产环境的 Agent 默认应该开启沙箱并且遵循最小权限原则。在社区讨论中经常有人纠结“set up default sandbox”还是“disabled no sandbox”。这里有一个很明确的建议任何涉及代码执行、命令调用的企业级 Agent 系统都不应该允许完全关闭沙箱。开发调试时可以放宽限制但生产环境的默认配置必须严格。2.4 Multi-Agent 编排模式流水线、编排者、黑板Multi-Agent 不是简单地把多个 Agent 堆在一起。目前常见的编排模式有三种。流水线模式是最容易理解的任务按顺序经过多个 Agent上游的输出是下游的输入。例如一个 Agent 负责解析需求另一个 Agent 负责生成代码第三个 Agent 负责测试。编排者模式是最多企业采用的有一个主控 Agent 负责拆解任务并把子任务分发给不同的执行 Agent执行完的结果再汇总回主控。这种模式的好处是主控 Agent 可以看到全局能够动态调整策略。黑板模式则是多个 Agent 共享一块公共信息区域各自读取、写入、更新状态。适合用于任务状态频繁变化、角色之间信息高度共享的场景。无论采用哪种模式Multi-Agent 的协作逻辑都应该由 Harness 统一管控否则就会出现节 1.2 中提到的消息混乱和日志黑洞问题。下面用一张表来对比这四个概念概念解决的问题通俗类比典型落地方式Harness控制 Agent 的执行边界与协作流程缰绳、驾驶舱生命周期钩子、策略引擎、审计模块Agent执行任务具备推理和工具调用能力干活的人大模型 Prompt 工具调用循环Skill复用和治理 Agent 的具体能力插件、技能包注册表、脚本、API 封装SandBox隔离执行风险控制越权行为隔离舱容器、虚拟机、受限子进程3. 企业级 Multi-Agent 协同架构设计与 Harness 的职责边界3.1 一个典型的企业级 Agent 系统分层架构从架构角度看一个成熟的企业级 Multi-Agent 系统通常分为五层。交互层负责和用户对接处理自然语言输入并返回结果通常表现为 Web 页面、IM 机器人或 API 网关。Harness 控制层是整个架构里最关键的一层。它不直接产生业务结果而是负责把用户请求转换为受控的任务执行流程。权限校验、沙箱检查、Agent 调度、日志记录都发生在这里。Agent 编排层包含具体的 Agent 实例。每个 Agent 负责特定角色例如需求分析 Agent、代码生成 Agent、测试 Agent。它们接收 Harness 分发的任务后通过自己的模型推理循环完成任务。Skill 与工具层是所有具体能力所在包括已注册的各个 Skill、业务 API、基础工具、模型调用客户端。沙箱与基础设施层提供代码执行环境、数据存储、网络策略、监控采集等底层能力。这种分层的好处在于每一层都有明确的职责和边界。模型再强大也只是 Agent 编排层中的一个组件工具再丰富也需要经过 Harness 控制层的调度和审批。3.2 一次真实任务在架构中的流转路径我们以“帮用户写一个函数并验证运行结果”这个任务为例看一次完整的请求如何流转。用户输入请求后交互层先做基本校验把翻译成内部格式再交给 Harness。Harness 对请求做安全扫描确认没有越权风险后把任务派发给需求分析 Agent。需求分析 Agent 通过模型推理把用户请求拆解为任务清单。Harness 收到任务清单后把“生成代码”的任务分发给代码生成 Agent。代码生成 Agent 编写 Python 代码并返回。接着Harness 又把代码交给测试 Agent测试 Agent 的代码在沙箱中执行。最后沙箱的执行结果被回传Harness 汇总所有中间记录把最终结果返回给用户。整个过程中模型只负责理解和生成内容真正控制流程的是 Harness。这样做的好处是如果某一步出错可以精准定位如果想限制某个 Agent 的权限可以在 Harness 层直接配置如果想审计可以从日志里还原整条链路。3.3 Harness 的职责边界虽然 Harness 很关键但它不应该什么都做。经验法则是和模型推理强相关的事情交给 Agent和执行流程、权限、安全强相关的事情交给 Harness和具体业务强相关的事情交给 Skill 和工具层。如果 Harness 介入业务过深会导致框架层代码频繁变动维护成本迅速上升。反之如果 Agent 自己处理权限和沙箱每次推理都会增加不必要的上下文负担也更容易出现绕过校验的风险。这种边界意识是 Harness Engineering 入门时最重要的一课。4. 环境准备与项目初始化4.1 运行环境要求接下来进入实操部分。为了保证示例在不同环境下都能跑通本文只依赖 Python 标准库不引入第三方框架便于读者理解核心机制。推荐环境如下Python 3.10 或更高版本操作系统Windows、macOS、Linux 均可不需要 GPU示例使用模拟模型客户端不实际调用大模型 API文本编辑器或 IDE推荐使用 VS Code 或 PyCharm。如果你希望把示例中的模型客户端替换为真实企业模型服务再自行接入 OpenAI、DeepSeek 或其他兼容 API 对应的 SDK 即可。版本请以实际项目为准本文重点演示核心思路。4.2 项目目录结构建议先按下面的结构创建工程目录harness-demo/ ├── main.py └── harness/ ├── __init__.py ├── engine.py ├── sandbox.py ├── agents.py └── skills/ ├── __init__.py └── skill_registry.py目录划分说明main.py是程序入口负责组装各个组件harness/engine.py定义 Harness 控制层的基类harness/sandbox.py定义沙箱策略和执行器harness/agents.py定义多个不同角色的 Agentharness/skills/skill_registry.py定义技能注册表。4.3 初始化 Python 工程在harness-demo目录下打开终端创建并激活虚拟环境。cd harness-demo python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate然后确认 Python 版本python --version本文示例不依赖第三方包因此不需要执行 pip install 操作。5. 从零实现一个可用的 Harness 工程5.1 定义 Harness 生命周期钩子首先实现 Harness 控制层的基类。这个基类最重要的作用是定义 Agent 执行过程中的生命周期钩子让后续所有 Agent 都能在调用工具前做权限校验、在调用后做审计记录。文件路径harness/engine.pyHarnessEngine 是所有 Agent 控制器的基类。 它定义了 Agent 执行过程中最重要的几个生命周期钩子。 from abc import ABC, abstractmethod class HarnessEngine(ABC): def __init__(self, agent_name, model_client, skill_registry, sandbox_policy): self.agent_name agent_name self.model_client model_client self.skill_registry skill_registry self.sandbox_policy sandbox_policy def before_tool_call(self, tool_name, tool_args): 工具调用前执行可以校验权限、改写参数、做审计。 if not self.sandbox_policy.is_allowed(tool_name, tool_args): raise PermissionError(fSandbox 拦截了工具调用: {tool_name}) def after_tool_call(self, tool_name, tool_args, result): 工具调用后执行可以记录结果、触发后续动作。 self.sandbox_policy.audit(tool_name, tool_args, result) def run(self, user_request): 主执行流程子类需要实现具体的决策循环。 self.on_start(user_request) final_result self.execute_loop(user_request) self.on_end(user_request, final_result) return final_result def on_start(self, user_request): print(f[Harness] {self.agent_name} 开始处理请求) def on_end(self, user_request, result): print(f[Harness] {self.agent_name} 处理结束) abstractmethod def execute_loop(self, user_request): raise NotImplementedError这里真正值得关注的是before_tool_call和after_tool_call两个钩子。它们意味着你可以把任何安全策略、审计逻辑、日志逻辑集中放在统一位置而不是散落在每个 Agent 里。这样做才能保证后续所有 Agent 都遵循相同的规范。另外run方法把请求执行和生命周期管理拆分开子类只负责实现决策循环不必关心统一的前置校验和后置记录。这种“模板方法”设计是 Harness 工程里最常见的代码结构。5.2 实现技能注册表 SkillRegistry接下来实现技能注册表。它的作用是统一管理所有可被 Agent 调用的 Skill提供注册、查询、自动发现三种能力。这里的自动发现功能会让你后续增加新技能时不需要修改过多代码只需把技能包放到指定目录即可。文件路径harness/skills/skill_registry.py技能注册表统一管理所有可被 Agent 调用的技能。 import importlib import pkgutil class SkillRegistry: def __init__(self): self._skills {} def register(self, skill_name, skill_entry, description): 手动注册一个技能。 :param skill_name: 技能名称 :param skill_entry: 可调用对象通常是函数 :param description: 技能描述供模型选择时参考 self._skills[skill_name] { entry: skill_entry, description: description, } def get(self, skill_name): 根据名称获取技能入口。 skill self._skills.get(skill_name) if skill is None: raise KeyError(f未注册的技能: {skill_name}) return skill[entry] def list_skills(self): 返回所有技能的名称和描述。 return [ {name: name, description: meta[description]} for name, meta in self._skills.items() ] def auto_discover(self, package_name): 自动扫描指定包下的技能模块。 约定每个技能模块必须暴露 SKILL_DESC 和 run 函数。 这种约定式设计可以降低团队新增技能时的理解成本。 package importlib.import_module(package_name) for module_info in pkgutil.iter_modules(package.__path__): module importlib.import_module(f{package_name}.{module_info.name}) self.register( skill_namemodule_info.name, skill_entrymodule.run, descriptionmodule.SKILL_DESC if hasattr(module, SKILL_DESC) else 无描述, )这里有一个很好的团队协作约定所有 Skill 模块必须暴露SKILL_DESC和run。这意味着团队写新技能时不需要理解复杂的框架代码只要照着这个约定写一个模块就能被 Harness 自动发现并纳入管理。描述信息中的SKILL_DESC在真实项目中非常重要因为大模型正是依靠这些描述来决定什么时候调用哪个 Skill。5.3 实现沙箱策略与执行器现在实现沙箱策略与执行器。这部分是企业级安全的核心所在。文件路径harness/sandbox.py沙箱策略隔离 Agent 执行的代码与系统。 这个实现是一个参考模型。在企业环境中 应接入容器、虚拟机或云厂商的隔离沙箱服务。 import subprocess import tempfile import os class SandboxPolicy: def __init__(self, allow_networkFalse, allowlist_commandsNone, max_exec_time_sec30): self.allow_network allow_network self.allowlist_commands allowlist_commands or [python3, ls, pwd] self.max_exec_time_sec max_exec_time_sec self.audit_log [] def is_allowed(self, tool_name, tool_args): 根据工具名称和参数判断是否允许执行。 if tool_name execute_command: command tool_args.get(command, ) parts command.split() base parts[0] if parts else return base in self.allowlist_commands if tool_name http_request and not self.allow_network: return False return True def audit(self, tool_name, tool_args, result): 记录审计日志便于事后回溯。 self.audit_log.append({ tool: tool_name, args: tool_args, result_preview: str(result)[:200], }) def execute_in_sandbox(self, code: str): 把代码写入临时目录并用受限子进程执行。 with tempfile.TemporaryDirectory() as tmp_dir: script_path os.path.join(tmp_dir, sandbox_script.py) with open(script_path, w, encodingutf-8) as f: f.write(code) try: result subprocess.run( [python3, script_path], capture_outputTrue, textTrue, timeoutself.max_exec_time_sec, checkFalse, ) return { stdout: result.stdout, stderr: result.stderr, returncode: result.returncode, } except subprocess.TimeoutExpired: return { stdout: , stderr: f执行超时超过 {self.max_exec_time_sec} 秒, returncode: -1, }这段代码里的核心参数是allowlist_commands。它限制了 Agent 能够执行的命令范围。如果 Agent 收到的任务是执行某个不在白名单里的命令is_allowed会直接返回 FalseHarness 层的before_tool_call就会抛异常。这就构成了第一道防线即使大模型被恶意 Prompt 诱导最终能执行的命令也被限制在一个很小的范围内。第二道防线是max_exec_time_sec任何代码执行都有超时保护避免 Agent 陷入死循环。5.4 实现多 Agent 协作示例下面定义三个角色不同的 Agent需求分析 Agent、代码生成 Agent、测试 Agent。它们分别继承 HarnessEngine分别实现自己的execute_loop。关键之处在于它们共享同一个SandboxPolicy因此安全策略保持一致。文件路径harness/agents.py具体的 Agent 实现示例。 from harness.engine import HarnessEngine class RequirementAnalystAgent(HarnessEngine): 需求分析 Agent负责把用户需求拆解为任务清单。 def execute_loop(self, user_request): self.before_tool_call(llm_generate, {}) requirement_list self.model_client.chat( f你是需求分析师请把下面的需求拆解成可执行的任务清单{user_request} ) self.after_tool_call(llm_generate, {}, requirement_list) return requirement_list class CodeGeneratorAgent(HarnessEngine): 代码生成 Agent根据任务清单生成 Python 代码。 def __init__(self, agent_name, model_client, skill_registry, sandbox_policy): super().__init__(agent_name, model_client, skill_registry, sandbox_policy) self.code_blocks [] def execute_loop(self, requirement_list): generated_code self.model_client.chat( f请为以下需求生成 Python 代码只输出代码{requirement_list} ) self.code_blocks.append(generated_code) return generated_code class TestAgent(HarnessEngine): 测试 Agent在沙箱中执行生成的代码并给出测试结论。 def execute_loop(self, generated_code): sandbox_result self.sandbox_policy.execute_in_sandbox(generated_code) review self.model_client.chat( f代码执行结果如下请判断是否符合预期{sandbox_result} ) return { sandbox_result: sandbox_result, review: review, }可以看到Agent 的业务逻辑非常简单需求分析 Agent 只负责调用模型做文本拆解代码生成 Agent 只负责调用模型生成代码测试 Agent 只负责把代码丢进沙箱执行。每个 Agent 都没有权限自行决定是否绕过沙箱因为before_tool_call和after_tool_call已经在基类里统一强制生效。如果未来需要新增审计埋点只需要在基类中修改一处所有 Agent 都会生效。5.5 编写启动入口最后写启动入口把所有组件组装起来。我在示例中使用一个模拟的模型客户端这样不依赖真实大模型服务也能跑通全流程。你在实际项目中可以把fakeTrue替换为真实的大模型调用。文件路径main.py程序入口组装 Harness 控制层与多个 Agent。 from harness.engine import HarnessEngine from harness.sandbox import SandboxPolicy from harness.agents import RequirementAnalystAgent, CodeGeneratorAgent, TestAgent from harness.skills.skill_registry import SkillRegistry class LocalModelClient: 示例用模型客户端。 在企业项目中请替换为真实的大模型 API 或私有化部署服务。 def __init__(self, fakeTrue): self.fake fake def chat(self, prompt): if self.fake: return f[mock response for]: {prompt[:80]} # 真实实现接入企业实际的大模型服务 raise NotImplementedError(请接入企业实际的大模型服务) if __name__ __main__: skill_registry SkillRegistry() sandbox_policy SandboxPolicy(allow_networkFalse) model_client LocalModelClient(fakeTrue) analyst RequirementAnalystAgent( agent_name需求分析Agent, model_clientmodel_client, skill_registryskill_registry, sandbox_policysandbox_policy, ) coder CodeGeneratorAgent( agent_name代码生成Agent, model_clientmodel_client, skill_registryskill_registry, sandbox_policysandbox_policy, ) tester TestAgent( agent_name测试Agent, model_clientmodel_client, skill_registryskill_registry, sandbox_policysandbox_policy, ) user_request 写一个函数输入两个数字返回它们的最大公约数并演示运行结果 requirement_list analyst.run(user_request) generated_code coder.run(requirement_list) test_result tester.run(generated_code) print( 需求分析结果 ) print(requirement_list) print( 生成代码 ) print(generated_code) print( 沙箱执行结果 ) print(test_result)5.6 运行与验证执行下面的命令python main.py预期输出中会出现三个 Agent 的处理日志以及“需求分析结果”“生成代码”“沙箱执行结果”三块内容。哪怕模型客户端是 mock 的你也应该能够看到整条 Multi-Agent 链路是完整走通的。如果某个 Agent 报错可以先检查是否是before_tool_call中沙箱策略拦截了不合规的调用。示例中所有 Agent 只调用了llm_generate而is_allowed对不认识的工具默认返回 True因此不会被拦截。真实项目中你要把is_allowed改成默认拒绝、只放行白名单中的工具这样才符合最小权限原则。6. 验证一个 Harness 是否“可用”的检查清单代码跑通只是第一步。在企业级项目中我们需要一套更严格的验证标准。下面这份检查清单可以用来评估你搭出来的 Harness 是否真正可落地。第一项是权限校验是否生效。你可以构造一个恶意工具名或一段包含危险命令的请求看看 Harness 是否会在工具调用前直接拒绝。如果还是放行说明权限钩子没有真正接进所有 Agent 的执行路径。第二项是沙箱隔离是否有效。让测试 Agent 执行一段带有rm -rf命令的代码确认它不会影响宿主机环境。在示例代码中沙箱执行的是临时目录里的子进程即使失败也只影响临时目录不会扩散到外部真实环境。生产环境更应该使用容器级隔离。第三项是日志链路是否完整。从用户请求进入 Harness 到最终返回中间每一步的 Agent、工具、耗时、结果是否都能找到记录。缺少日志链路的话生产环境一旦出问题你连排查的入口都没有。第四项是失败恢复是否明确。当某个工具调用抛出异常、某个 Agent 超时、沙箱返回错误时系统有没有对应的降级策略。一个健壮的 Harness 应该支持告警、重试、跳过、中止等多种策略而不是默默吞掉异常。第五项是 Skill 注册是否可审计。技能库里有哪些技能、分别由谁维护、哪个版本在使用、变更历史是什么这些都要有记录。Skill 一旦多起来没有治理就会变得混乱。第六项是上下文长度和成本是否可控。Multi-Agent 每次交互都可能引入大量上下文要提前设计好 Token 使用上限和费用监控。在实际项目中这一步往往比功能开发更容易踩坑。7. 常见问题与排查思路在企业项目里Harness、Multi-Agent、SandBox 和 Skill 的配合并不总是一帆风顺。下面整理了一些高频问题和对应的排查思路。问题现象可能原因排查方式解决方案Agent 反复调用同一个工具停不下来缺少最大迭代次数限制查看 Harness 日志中工具调用次数在 Harness 层增加循环次数上限沙箱模式下网络请求失败沙箱默认关闭网络访问查看沙箱策略配置按需开启白名单域名而不是全局放行生成的代码被沙箱拒绝执行代码里包含非白名单命令查看is_allowed返回的异常信息隔离或规范化代码生成 Prompt多个 Agent 之间日志混乱缺少统一 Trace ID检查 Harness 日志是否带请求 ID在请求入口生成 Trace ID 并贯穿所有日志新 Skill 无法被模型选中Skill 描述写得不够清晰打印 Skill 列表检查描述信息补充使用场景、示例和入参说明生产环境偶发超时外部 API 不稳定或超时设置过短查看模型调用耗时和重试记录增加超时退避重试策略沙箱被完全关闭系统风险升高配置项被误改成 disabled no sandbox检查配置中心和审计记录禁止生产环境关闭沙箱单独说一下最常见的循环问题。很多团队第一次跑 Multi-Agent 时都会遇到“Agent 停不下来”。解决方案很简单在 Harness 控制层维护一个计数器每次执行循环加一超过阈值就强制终止并返回当前已经完成的中间结果。这种策略并不复杂但必须在框架层实现不能指望每个 Agent 自己控制。关于 “Skill 不被模型选中” 的问题我的建议是把描述写得像“给同事的功能说明”一样具体包含触发场景、示例输入、输出结构。模型本质上是通过描述去匹配任务描述越模糊误选概率越高。8. 企业落地 Harness Engineering 的最佳实践8.1 安全边界最小权限是默认原则企业级 Agent 系统最容易踩的坑就是开发时为了方便把权限全部放开。等系统上线后一次工具调用错误就可能造成无法挽回的损失。最佳实践是所有权限默认关闭按需开放。具体包括命令白名单只包含业务必需的命令网络访问默认关闭只开放必要域名Skills 和工具尽量提供最小化、不可变参数所有涉及删除、写入生产数据的操作必须走审批流程。安全边界不是开发完成后补上去的而是要从 Harness 基类设计时就开始强制实现。8.2 可观测性没有日志就没有复盘机会在生产环境里一个 Multi-Agent 系统的调试难度远高于单体服务。因为每个 Agent 都有一次模型调用和至少一次工具调用请求链路天然较长。建议在 Harness 层统一埋点为每次请求生成唯一 Trace ID并记录以下关键信息Agent 名称和版本输入输出摘要模型名称、Token 消耗、耗时工具名称、参数、返回结果、返回码沙箱执行结果或错误信息。有了这些数据你可以快速定位影响整体结果的具体环节。8.3 Skill 治理所谓“自我进化”其实是一套版本纪律热词里经常提到“自我进化的 Skill”这里给出一个工程化的理性理解Skill 的进化不是模型自己悄悄修改自身权重而是指技能库的迭代闭环。当某个 Agent 在运行过程中发现一种更高效的用法团队可以把这种用法固化成一个新的 Skill或者更新已有 Skill 的描述和逻辑。经过沙箱验证和人工评审后新版本替换旧版本旧的归档保存。这本质上是一套版本治理体系。一个企业级的 Skill 仓库应当有明确的命名规范、版本号、作者、变更记录和测试用例。这样技能库才能像代码库一样健康迭代而不是越用越乱。8.4 生产环境变更备份、灰度、回滚缺一不可如果 Harness 配置或 Skill 变更要部署到生产环境务必先在测试环境验证。按照以下节奏执行对当前配置和知识库做完整备份灰度发布到小流量环境观察日志和成功率确认稳定后再全量发布如果出现异常立即回滚到上一个稳定版本。另外涉及数据库写入或删除操作时必须先经过备案和审批并在测试环境用脱敏数据完整验证避免生产误操作。8.5 团队协作统一约定比框架选型更重要最后想强调一点Harness Engineering 本质上是一项团队工程。无论你最终选择基于开源项目封装还是完全自研都比不上团队内部达成一套统一约定更重要。举例来说每个 Skill 模块必须暴露哪些字段、每个 Agent 必须实现哪个生命周期方法、每类日志必须包含哪些内容这些约定一旦定下来后续的维护成本会大幅下降。建议团队内部形成一份简短的开发规范文档把命名、注册、日志、安全、版本这五件事写清楚。往往这份文档的价值会超过某一次技术选型。9. 下一步怎么学Harness Engineering 不是只靠读文章就能掌握的技能真正有效的方法是在小项目里亲手把框架搭一遍。你可以从这个示例出发完成以下三步练习。第一步把示例中的LocalModelClient替换为真实大模型调用让它从 mock 输出变成真实推理观察全链路是否仍然稳定。第二步新增一个数据分析 Skill 并注册到SkillRegistry让测试 Agent 在沙箱中调用这个技能理解“技能注册 — 模型选择 — 沙箱执行”的完整链路。第三步设计一个真实的内部场景例如“自动整理周报并发送给团队成员”把流程拆解为多个 Agent 角色并在 Harness 层加上权限和日志。当你把这些练习做完再回头看 Codex Harness、DeepSeek Harness 以及其他社区方案时你会更清楚它们的设计意图也更有能力判断哪些功能可以直接使用、哪些需要自己扩展。2026 年的企业级 AI 大模型应用拼的不是模型的单一智商而是整个 Harness 体系能否把模型装进一条可控、可靠、可回溯的生产链路里。早一步把这个框架搭好你的团队就多一分从 Demo 走向生产的底气。