Harness Engineering 通识如何构建可靠的 AI Agent 基础设施摘要当所有人都在关注模型能力时真正的差异化正在向下移动到 Harness 层。本文从 OpenHarness 等开源项目出发系统讲解 Agent Harness 的核心架构、关键组件和工程实践帮助你理解model decides what, harness handles how safely的深层含义。为什么需要 Harness Engineering2026 年的 AI 开发生态出现了一个有趣的现象模型能力趋同但 agent 体验差异巨大。同样的 Qwen3.5-Plus 或 Kimi K2.5在不同的 agent 系统中表现判若两人。根因在于模型只提供 intelligenceharness 才提供 hands、eyes、memory 和 safety boundaries。Agent Model (intelligence) Harness (infrastructure)Harness Engineering 的核心价值安全边界- 权限控制、审计日志、拒绝追踪可观测性- token 计数、成本追踪、决策日志可靠性- 重试机制、降级策略、确定性兜底扩展性- 工具生态、技能系统、多 agent 协调Harness 的核心架构1. Agent Loop引擎所有 agent harness 共享同一核心模式whileTrue:# 1. 调用模型流式响应responseawaitapi.stream(messages,tools)# 2. 检查是否完成ifresponse.stop_reason!tool_use:break# 模型完成任务# 3. 执行工具调用fortool_callinresponse.tool_uses:# Permission check → Hook → Execute → Hook → Resultresultawaitharness.execute_tool(tool_call)messages.append(tool_results)# 4. 循环继续 - 模型看到结果决定下一步关键设计点流式处理- 降低首 token 延迟支持长任务 progress updates工具调用解析- 结构化输出验证错误恢复循环终止条件- 最大轮次控制、token 预算、超时保护2. 工具系统Tools工具是 harness 的手。典型分类类别工具示例关键能力File I/ORead, Write, Edit, Glob, Grep权限检查、路径沙箱ShellBash命令白名单、超时控制SearchWebSearch, WebFetch速率限制、结果缓存AgentSubagent, SendMessage隔离执行、结果聚合TaskTaskCreate, TaskStop后台生命周期管理MCPMCPTool, ListResources协议适配、资源发现工程要点Pydantic 输入验证- 结构化、类型安全的参数自描述 JSON Schema- 模型自动理解工具用途权限集成- 每次执行前检查Hook 支持- PreToolUse/PostToolUse 生命周期3. 权限与安全Permissions生产级 harness 必须有多级权限控制{permission:{mode:default,path_rules:[{pattern:/etc/*,allow:false}],denied_commands:[rm -rf /,DROP TABLE *]}}三级权限模式模式行为使用场景Default写/执行前询问日常开发Auto允许所有沙箱环境、CI/CDPlan Mode阻止所有写入大型重构、先审查Hooks 机制PreToolUse- 工具执行前检查审计、配额、依赖验证PostToolUse- 工具执行后审计结果记录、副作用追踪4. 记忆系统MemoryHarness 的记忆分层┌─────────────────────────────────────┐ │ Active Context (RAM) │ ← 当前任务 working set ├─────────────────────────────────────┤ │ Retrieval Layer (Index) │ ← 按需检索 ├─────────────────────────────────────┤ │ Durable Memory (Disk) │ ← 跨 session 事实/事件 └─────────────────────────────────────┘关键原则Context window ≠ Memory- 窗口是 RAMmemory 是 durable storeLibrary vs Episodic- 静态文档与动态事件历史分开Eviction Policy- 索引可淘汰原始事件最好保留审计/debug5. 技能系统Skills技能是可复用的指令 工作流打包单元--- name: code-review description: Systematic code review for bugs and quality --- # Code Review Skill ## When to use Use when the user asks for code review. ## Workflow 1. ASSESS: Check file size, language, diff scope 2. ANALYZE: Read code, identify patterns 3. PLAN: Prioritize issues (critical → minor) 4. EXECUTE: Generate review comments 5. VALIDATE: Ensure actionable feedback设计要点按需加载- 避免 context bloat93% tokens 可能是未使用工具定义阶段化执行- ASSESS→ANALYZE→PLAN→EXECUTE→VALIDATE兼容生态- OpenHarness 直接兼容 anthropics/skills 和 claude-code/plugins6. 多 Agent 协调CoordinatorHarness 支持子代理生成和团队协作# 主 agent 生成子代理subagentawaitharness.spawn_subagent(rolesecurity-auditor,tools[read,grep,glob],# 最小权限memoryisolated# 独立内存空间)resultawaitsubagent.execute(task)关键模式AWS-style least-privilege- 每个子代理只有所需工具并行执行- 独立域检查并发运行orchestrator 聚合持久化记忆- 沉淀 recurring failure signatures而非塞满主会话Harness Engineering 最佳实践1. 确定性兜底Deterministic BackstopLLM 是非确定性的harness 必须提供确定性保障# 错误示例完全依赖 LLMsecurity_analysisawaitllm.analyze(code)# 正确做法确定性规则 LLM 增强yara_resultsawaityara.scan(code)# 确定性llm_resultsawaitllm.augment(yara_results)# 补充final_reportmerge(yara_results,llm_results)实践要点YARA 规则、静态分析作为兜底LLM 做 augmentation而非唯一真相结构化输出强制schema validation2. 决策可观测性Decision ObservabilityAgentic system 进入会采取行动阶段后仅记录 prompt/output 已不足{decision_log:{goal:Fix the authentication bug,retrieved_context:[auth.py:45-67,session.md],tool_calls:[{name:read,args:{...}}],reasoning_path:Step 1 → Step 2 → Step 3,chosen_action:Edit auth.py line 52,outcome:Success}}为什么重要Debugging / Audit / GovernanceAutonomous failure 事后重建合规要求金融、医疗等受监管行业3. 执行控制平面Execution Control PlaneLoop and hope型 agent 风险在于模型直接持有执行权┌──────────────┐ propose ┌──────────────┐ │ LLM │ ──────────────── │ Deterministic │ │ (Intelligence)│ │ DAG/Contract│ └──────────────┘ └──────────────┘ │ ▼ execute ┌──────────────┐ │ External │ │ Systems │ └──────────────┘更安全架构LLM 只 propose actions确定性 DAG/contract 层负责真正执行强制 explicit permissions / scoped resources / immutable audit logs4. 工具流式输出Tool StreamingLLM 更适合做DJ而不是singer——负责决定调用什么工具、如何解释结果但不应被迫充当所有 tool output 的 transport layer┌─────────┐ tool_call ┌─────────┐ │ LLM │ ──────────── │ Tool │ └─────────┘ └─────────┘ ▲ │ │ semantic_result │ event_stream │ (compact) │ (direct to client) │ ▼ │ ┌─────────┐ └────────────────────│ Client │ └─────────┘更合理的 tool contractsemantic_result- 紧凑状态回流模型event_stream- 长文本/音频/图像/进度直接流向 client5. Harness Knobs调优参数同一模型改 harness 可提升 52.8%→66.5%13.7%效果Knob说明影响System Prompt角色定义、行为约束高Tools工具集选择、描述质量高MiddlewareHooks、重试策略、缓存中Context Management索引、压缩、检索策略高Permission Mode默认权限、路径规则中实战从零构建 Harness步骤 1定义 Agent LoopclassAgentHarness:def__init__(self,api,tools,permissions):self.apiapi self.toolstools self.permissionspermissions self.messages[]asyncdefrun(self,prompt,max_turns10):self.messages.append({role:user,content:prompt})forturninrange(max_turns):responseawaitself.api.stream(self.messages,self.tools)ifresponse.stop_reason!tool_use:breakfortool_callinresponse.tool_uses:ifnotself.permissions.check(tool_call):raisePermissionError(fBlocked:{tool_call.name})resultawaitself.tools.execute(tool_call)self.messages.append({role:tool,content:result})returnself.messages[-1][content]步骤 2实现工具系统frompydanticimportBaseModel,FieldclassReadFileInput(BaseModel):path:strField(descriptionFile path to read)limit:intField(default2000,descriptionMax lines to read)classReadFileTool(BaseTool):nameread_filedescriptionRead contents of a fileinput_modelReadFileInputasyncdefexecute(self,args:ReadFileInput)-ToolResult:# Permission checkifnotself.permissions.allow_path(args.path):returnToolResult(errorfPath not allowed:{args.path})# Executewithopen(args.path)asf:lineslist(islice(f,args.limit))returnToolResult(output.join(lines))步骤 3添加 HooksclassHookRegistry:def__init__(self):self.pre_tool_use[]self.post_tool_use[]defregister_pre(self,hook):self.pre_tool_use.append(hook)defregister_post(self,hook):self.post_tool_use.append(hook)# 使用示例hooksHookRegistry()hooks.register_preasyncdeflog_tool_call(tool_call):print(fCalling:{tool_call.name}({tool_call.args}))hooks.register_postasyncdefaudit_result(tool_call,result):awaitaudit_log.write(tool_call,result)步骤 4实现权限系统classPermissionEngine:def__init__(self,config):self.modeconfig[mode]self.path_rulesconfig[path_rules]self.denied_commandsconfig[denied_commands]defcheck(self,tool_call):ifself.modeauto:returnTrueifself.modeplan:returntool_call.namein[read,glob,grep]# Default mode: check rulesiftool_call.namebash:fordeniedinself.denied_commands:ifdeniedintool_call.args.get(command,):returnFalsereturnTruedefallow_path(self,path):forruleinself.path_rules:iffnmatch(path,rule[pattern]):returnrule[allow]returnTrue# Default allowHarness Engineering 的未来1. 标准化趋势MCP (Model Context Protocol)- model↔tool/data transport 标准A2A (Agent-to-Agent)- 跨 agent 协调协议ACP (Agent Communication Protocol)- 企业级消息协议2. 分层架构┌─────────────────────────────────────┐ │ Application Layer (Workflows) │ ← 业务逻辑 ├─────────────────────────────────────┤ │ Orchestration Layer (Coordinator) │ ← 多 agent 协调 ├─────────────────────────────────────┤ │ Harness Layer (Tools/Memory) │ ← 基础设施 ├─────────────────────────────────────┤ │ Model Layer (LLM APIs) │ ← intelligence └─────────────────────────────────────┘3. 可组合性未来 harness 将更像乐高积木可插拔工具提供商可替换记忆后端Mem0/VectorStore/SQLite可配置权限策略可扩展技能生态总结Harness Engineering 的核心洞察模型是 intelligenceharness 是 infrastructure- 两者分离是工程化的必然安全不是外围模块是架构本体- 权限、审计、hooks 必须内建可观测性决定可维护性- 决策日志、token 追踪、成本分析缺一不可确定性 概率性 可靠系统- LLM 做 augmentation规则做兜底生态决定长期竞争力- 技能系统、插件兼容、工具丰富度当所有人都在卷模型时真正的护城河正在 harness 层形成。参考项目OpenHarness: https://github.com/HKUDS/OpenHarnessClaude Code: https://github.com/anthropics/claude-codeLangChain Deep Agents: https://github.com/langchain-ai/langchain延伸阅读Agent Engineering: Build→Test→Ship→Observe→RefineExecution Control Plane: Intelligence-Execution SplitDecision Observability: Beyond Prompt/Output Logging作者ken-kit | 发布日期2026-04-03