开源【智能体Harness工程指南】——第一部分：Harness工程基础

第一章Harness工程概论要理解当前系统工程能力比模型能力本身更为关键理解驾驭这个词是约束、可验证性、层次化的信任机制Harness的五大核心子系统和两大基础保障。另外一本书中也提到了harness拆分为5个部分1.1 从大语言模型到智能体的快速过渡LLM从实验室走向生产环境遇到的问题可靠性问题同样的问题同一个模型的多次回答可能差异巨大外部交互成本控制大规模调用API的成本快速增长需要更精细的控制和优化安全性问题让LLM任意调用系统权限和外部接口存在严重的安全风险一个Agent需要的三个核心能力思维能力行动能力学习能力从结果中反馈、调整策略、积累经验涉及记忆机制、强化学习信号、迭代优化等为什么还需要构建复杂的系统工程层在于可靠性和可控性的鸿沟。Harness要让智能体更可靠、更可控、更安全。Harness工程将一个理论上的智能体概念转化为生产级别的系统1.2 Harness的定义和职责边界Harness是在大语言模型与真实执行环境之间构建的一套系统工程框架通过标准化的消息协议、分层的权限管理、多维的执行可见性和完善的错误处理机制使得LLM能够在受控约束下安全、可靠地感知环境、执行任务、学习反馈。核心要素中间层角色harness本质上是一个适配器和控制层在LLM和执行环境之间我觉得这句话很直白不替代LLM产生业务推理也不直接承担工具内部逻辑而是把LLM的意图转换为可验证、可授权、可执行的操作并将结果正确反馈给LLM。约束和可控性Harness主要目标不是扩展智能体的能力而是限制智能体的风险。将智能体行为控制在安全边界内。完整的生命周期管理在各个过程需要在整个智能体执行周期中保持可见性和控制力所以说harness通常指包裹在模型外面负责把模型能力安全可靠地接到真实世界的那一层harness承接意图转成可验证、可授权、可执行的操作并把结果回传。harness是LLM和外部世界的唯一通道。harness与传统中间件的区别在分布式系统中中间件Middleware也提供适配转发可见性等功能。传统中间件的假设参与交互的各方都是确定的行为可预测中间件的工作是高效转发消息、处理协议转换、管理连接harness的假设Agent的决策可能包含错误理解偏差甚至不当意图harness需要对agent的每一个决策都进行验证、授权、隔离执行传统中间件通常不会在转发请求前拦截和验证请求的合法性对某些危险操作进行权限检查或人工审批在执行失败时自动进行智能重试或降级为每个操作维护完整的审计日志而这些恰好是 Harness 的核心职责Harness做的事工具集成负责将各种外部工具和系统集成进来无论是API调用数据库查询文件操作还是系统命令。维护一个统一的工具注册表确保每个工具都有清晰的接口定义、权限配置和使用说明。权限和授权实现梯度化权限管理对于高危操作Harness可以拦截请求记录意图等待人工审批。**执行跟踪和验证**每一个工具调用都被记录、追踪和验证如果工具返回了意外的结果harness需要识别这些异常并决策是否重试降级或报告状态管理harness维护智能体执行过程中的完整上下文状态当智能体被中断或故障后可以恢复到一致的状态可观测性和审计通过日志、分布式追踪、性能指标等多个维度记录Agent的每个行为和决策不仅用于故障排查更是合规性和安全审计的基础上面五个部分就和之前看到的harnese五个部分类似harness不做的事业务推理和任务分解工具的实际执行模型的优化和训练业务逻辑通过harness层实现了安全性权限层确保不会有非法操作可靠性追踪和验证层确保即时出错也能快速定位可用性harness的重试和降级机制确保系统韧性DeerFlow的后端中间件DeeFlow的中间件层正式前面讨论的harness思想的一个典型工程实现并非传统意义上的消息转发中间件而是一套包裹在agent循环外部的可插拔、有状态的治理链。agent运行时基于langgraph和langchain构建核心是lead agent所有中间件都实现langchain的agentMiddleware接口在模型调用前后before_model/after_model或工具调用前后wrap_tool_call执行以读写agent状态这些中间件按严格顺序组成一条洋葱责任链请求从最外层向内穿透逐层完成清晰、准备和验证响应则从核心向外回溯逐层完成审计、整理和反馈。中间件按职责分层最外层输入清洗与安全边界中间件核心职责生命周期InputSanitizationMiddleware最外层清洗中和用户消息中的提示注入标签如防止恶意指令进入LLMbefore_modelToolOutputBudgetMiddleware截断过长的工具输出防止上下文被撑爆wrap_tool_callToolResultSanitizationMiddleware清晰远程内容工具如web_fetch的结果防止攻击者控制的网页伪造框指令wrap_tool_call运行时状态与资源准备中间件核心职责生命周期ThreadDataMiddleware为每个会话创建隔离的工作目录before_agentUploadsMiddleware将新上传的文件注入对话上下文并去重before_agentSandboxMiddleware获取并分配沙箱实例隔离代码执行环境before_agentDanglingToolCallMiddleware为被中断的工具调用注入占位响应保持消息历史完整before_agent安全与授权工具调用的安检员中间件核心职责生命周期GuardrailMiddleware工具调用的授权检查点每次工具执行前通过AuthorizationProvider验证权限采用失败即阻断策略wrap_tool_callSandboxAuditMiddleware对bash命令进行专门的安全审计和正则阻断wrap_tool_callReadBeforeWriteMiddleware文件修改前强制校验SHA256哈希防止基于过期内容的写入wrap_tool_call流程管控防失控与资源管理中间件核心职责生命周期LoopDetectionMiddleware检测并打破Agent的重复工具调用死循环after_modelSubagentLimitMiddleware限制单轮中并行子Agent的数量防止资源耗尽before_modelTokenUsageMiddleware追踪每次模型调用的Token消耗用于成本控制after_modelSummarizationMiddleware上下文接近token上限时自动压缩历史消息before_modelMemoryMiddleware跨会话记忆的注入与队列更新before_model/ after_agentTodoListMiddleware在计划模式下维护可见的任务列表after_modelClarificationMiddleware必须最后执行拦截澄清请求并转化为面向用户的提问after_modelTitleMiddleware首次交互后自动生成会话标题after_modelViewImageMiddleware为支持视觉的模型注入图像数据before_modelDeerflow允许在config.yaml中注册自定义中间件按业务需求注入领域护栏工具治理或可观测性钩子无需修改核心代码。1.3 五大核心子系统总览这里也是将harness系统分为了五个核心子系统和两大基础保障。五大核心子系统运行时引擎职责实现智能体的执行循环协调各个子系统的交互维护智能体执行的主循环通常遵循核心职责状态机管理消息编排异步执行在I/O等待期间不阻塞并发处理多个智能体任务超时和中断设置合理的执行超时支持优雅的任务中断和清理工具层职责抽象和管理各种外部工具的访问提供统一的接口调用核心职责工具注册工具发现参数验证权限检查执行隔离结果保准化记忆子系统职责管理智能体的各种记忆支持上下文理解和学习记忆子系统让智能体能够学习、改进和个性化响应模型集成与输出治理职责管理与LLM的交互控制和验证模型的输出解决一个关键问题LLM的输出不一定总是可靠的需要在充分利用LLM能力的同时防止其产生幻觉矛盾或危险的决策核心职责模型选择提示词管理输出解析输出验证降级策略当输出质量不满足要求时进行重试、提示词调整、或切换到更强大的模型编排引擎职责支持复杂的多步任务和多智能体协作编排引擎提供了一套机制让多个智能体能够协同完成任务核心职责工作流定义依赖管理智能体分配结果聚合故障恢复两大基础保障安全层职责在整个智能体生命周期中防止安全威胁和风险包括权限管理沙箱隔离输入验证输出过滤审计日志可观测性职责提供对harness系统运行的完整可见性为什么需要因为一个无法观测的系统一旦出现问题就很难诊断和修复可观测性提供了三个维度的视图日志Logs记录详细的事件序列支持文本搜索和过滤追踪Traces跟踪单个请求或任务的完整执行路径显示各个组件的耗时指标Metrics收集系统级别的性能指标如吞吐量、延迟、错误率支持告警和趋势分析子系统间的交互典型的Agent执行流程1.4 Harness为什么比模型更重要公开案例OpenAI Codex提示词优化Anthropic Constitution AI等用了Harness层之后许多错误会在执行前或执行后被发现并修正能够改变最终可用率理解Harness比模型更关键需要回到Agent系统的本质。大语言模型的本质是概率机器就是概率生成模型给定上下文生成最可能的下一个token。导致不可能完全消除错误确定性需求无法满足实时学习困难系统级别的可靠性无法仅通过提升单个LLM调用的准确率来实现必须在系统工程层面进行干预。以claude为例harness组件占据了核心地位实战建议不要过度优化模型模型准确率高了有边际效应重点转向系统工程优先投入高效益的harness组件把模型的最后一英里交给harness提前规划故障处理想到这一步失败了怎么办Harness不只是比模型更重要设计空间本身已经大到值得用自动化方法去搜索1.5 MiniHarness项目介绍目标是完成构建一个完整可运行的harness系统原型先快速搭建和运行miniharness克隆并下载项目git clone https://github.com/yeasy/harness_engineering_guide进入项目cd harness_engineering_guide/lab创建虚拟环境python3 -m venv venvwindows下激活虚拟环境venv \Scripts\activate安装依赖pip install -e .[dev]配置示例模型密钥在 .env中进行配置cp .env.example .env然后可以运行基本测试pytest .\tests\unit\test_core.py核心依赖pydantic数据验证和序列化httpxhttp客户端asyncio异步编程python-dotenv环境变量管理anthropicclaude apioepnaiapenAPIpyyamlyaml解析pytest单元测试pytest-asyncio异步测试black代码格式化pylint,代码质量检查mypy类型检查miniharness的项目结构lab/project.toml项目配置和依赖READEMD.md项目说明.env.example环境变量说明mini_harness/源代码目录init.pycore/ 核心接口定义agent.py智能体基础类message.py消息类型定义tool.py工具接口event.py,事件定义runtiem/运行时引擎init.pyengine.py智能体执行循环events.py运行时时间models.py运行时数据模型tools/工具实现init.pyregistry.py工具注册表builtin.py内置工具示例memory/记忆子系统init.pystorage.py记忆存储context.py上下文组装consolidation记忆整合models/ 模型集成init.pyprovider.py模型提供者parser.py响应解析quality.py输出质量门控orchestration/任务编排init.pyengine.py编排引擎与状态机mcp/mcp协议集成init.py,integration.pymcp工具注册与适配reliability/可靠性与可观测性init.pytracing.py链路追踪monitoring.py监控指标收集logging.py日志记录resiliience.py容错与重试机制security/安全防护init.pypermission.py权限决策引擎path-validator.py路径校验与标准化guardrails.py危险操作检测secure_executor.py安全执行器utils/ 工具函数init.pycofing.pyminiharness支持自定义和扩展importasynciofrommini_harness.runtime.engineimportRuntimeEnginefrommini_harness.tools.registryimportToolRegistryfrommini_harness.tools.builtinimportBashTool,FileReadTool,FileWriteToolasyncdefmain():# 构建工具注册表并注册内置工具registryToolRegistry()registry.register(BashTool())registry.register(FileReadTool())registry.register(FileWriteTool())# 创建运行时引擎就把注册工具给到engineRuntimeEngine(tool_registryregistry)# 运行并消费事件流asyncforeventinengine.run(帮我运行bash打印hello from miniharness):safe_keys{turn_number,tool_name,is_error,content_length}safe_metadata{k:vfork,vinevent.metadata.items()ifkinsafe_keys}print(f[{event.__class__.__name__}]{safe_metadata})if__name____main__:asyncio.run(main())第二章Harness架构全景这里书中概括为三层架构 横切关注点。三层架构接入层、编排层、智能体核心层两个横切关注点安全性和可观测性2.1 通用参考架构了解了五大核心和两大基础保障。还需要理解这些子系统如何组织如何交互的。因此书中给出了一个架构模型基于行业的最佳实践的抽象简单系统可以裁剪强实时、强合规或嵌入式场景可能需要变体。三层详细接入层Access Layer系统与外部世界的边界负责接收用户请求、协议转换和响应格式化CLI, Web API, SDK都属于接入层的实现形式编排层Orchestration Layer负责复杂任务的分解、多智能体的协调和工作流管理。负责分配子任务、任务依赖和聚合结果智能体核心层Agent Core Layerharness核心执行引擎包含运行时引擎工具层记忆子系统和模型集成与输出治理四个子系统在运行时引擎的同一循环中交替协作而非分层调用横切点安全可观测性存储接入层是Harness系统的交互入口协议适配将不同来源请求统一转换为内部任务格式身份认证响应格式化接入层做格式转换和路由分发编排层负责任务级别的调度任务分解依赖管理识别子任务间的依赖关系构建执行DAG多智能体协调结果聚合智能体核心层模型调用、工具执行、记忆更新并非各自独立的层级而是在运行时引擎的同一个循环中交替发生运行时引擎管理生命周期维护消息类型系统和执行状态协调其他三个子系统的调用顺序处理错误恢复和漂移检测模型集成与输出治理模型集成负责与LLM的交互支持多种LLM管理提示词和系统消息处理token限制和成本优化支持流式和批量调用输出治理负责处理LLM输出中最不确定的部分格式校正如果LLM没有返回期望的json格式尝试修复语义验证检查工具调用的参数是否合理是否调用了不存在的工具安全检查检查输出是否包含有害内容或违反约束置性度评估评估LLM对其输出的置信度低置信度时触发重试或人工审批要理解为什么需要输出治理因为LLM的输出是不可预测的要应对这种不确定性的防线例如一个示例先将输出文本解析为json然后校验格式解析失败让LLM自己修复然后进行语义验证进行安全检查层间通信设计原则了解了每一层的职责还要定义层间的通信方式向下的调用上层调用下层应该使用明确的、类型安全的接口类型安全指每个方法的输入参数和返回值都有明确的类型声明这样在开发阶段就能发现参数传错的问题而不是等到运行时报错。向上的反馈下层向上层报告时应该使用事件或回调机制而不是异常事件更像日常的工作汇报对于监控和调试系统至关重要例如通过事件机制进行汇报dataclassclassExecutionEvent: 表示系统中发生的一个事件 所有层都可以发出事件上层可以订阅这些事件监控系统运行状态 timestamp:datatime# 事件发生时间level:str# 严重程度source:str# 事件来源message:str# 可读描述context:dict# 附加信息classAgentCore:def__init__(self,event_handler:Callable[[ExecutionEvent]None]): 构造方法接收一个事件处理函数回调函数 Callable[[ExecutionEvent], None]是 接收ExecutionEvent参数不返回值的函数 这个函数由上层提供上层决定接收事件后做什么例如写日志、告警等 下层只负责发出事件不关心上层如何处理 self.event_handlerevent_handlerasyncdefrun(self,task:Task):# 发出任务开始事件self.event_handler(ExecutionEvent(timestampdatetime.now(),levelinfo,sourceAgentCore,messageTask started,context{task_id:task_id}))# 后续逻辑))