文章目录1. Harness Engineering驾驭工程1.1 定义1.2 发展历史1.3 VS Agent 框架1.4 主流开源 Harness 框架2. AgentScope Harness 架构2.1 定位2.2 核心工作原理2.3 核心能力一览2.4 状态流转2.5 自定义 Middleware 注意事项3. 快速开始3.1 依赖3.2 最小示例3.4 带工具 多轮对话3.5 三种文件系统模式3.6 技能Skill3.7 Spring Boot 完整示例1. Harness Engineering驾驭工程1.1 定义Harness Engineering驾驭工程是AI智能体Agent时代新一代系统化工程范式行业标准公式Agent 大模型 Model Harness 驾驭系统其中Model模型GPT、Claude、DeepSeek等大模型只负责推理、生成、思考如同千里马Harness包裹模型的整套运行控制系统、约束环境、反馈闭环、调度基础设施马具、跑道、管控规则。引用Anthropic官方定义支撑长周期复杂Agent稳定运行的外部框架、安全控制结构、任务编排系统。分为三层体系执行Harness工具调用、任务拆解、子代理调度负责干活评估Harness自动化校验、打分、结果比对判断对错控制Harness沙箱隔离、权限、行为白黑名单划定边界1.2 发展历史2025-11-26Anthropic发布《Effective harnesses for long-running agents》首次在官方技术博客把外部运行系统命名为Harness将Claude Agent SDK定义为通用Harness载体社区开始零散使用Agent Harness词汇但无统一工程方法论。2026-02HashiCorp Mitchell Hashimoto正式提出Harness Engineering完整工程方法论统一术语、三层架构、迭代哲学瞬间席卷硅谷与国内AI工程圈。OpenAI跟进发布《Harness engineering: leveraging Codex in an agent-first world》白皮书公开Codex生产级Harness落地流程。LangChain创始人、Martin Fowler等技术权威背书Harness Engineering取代Prompt Engineering成为生产Agent第一工程范式。2026 Q2 大量开源框架、评估基准、安全组件集中发布形成完整生态。1.3 VS Agent 框架Agent开发框架vsAI Harness运行框架 对比表:对比维度Agent框架LangChain、CrewAI、AutoGen、Vercel AI SDKAI Harness框架AgentScope、OpenHarness、DeepAgents、Harbor核心定位模块化开发SDK、代码组装工具库受控完整运行时容器、生产驾驭底座设计目标提供Agent基础原子组件让开发者自定义流程约束模型行为、保障长任务稳定、安全可落地上线核心内置能力LLM封装、基础Memory、Tool基类、Chain流程、多Agent通信抽象沙箱隔离、细粒度权限、断点续跑、自动校验反思、人在回路、全链路观测、持久状态快照、故障回滚安全体系无原生安全防护沙箱/权限需业务自行编码实现原生多层安全围栏操作白名单、高危指令拦截、资源配额、数据脱敏、审计日志灵活自由度极高循环逻辑、记忆策略、调度方式完全自定义中等底层运行规则固化仅支持配置化微调无法推翻驾驭主循环依赖层级最底层组装零件可被Harness封装在内外层运行容器可内嵌Agent框架作为内部组件上手方式手写代码拼装Agent每一环脚手架模式配置驱动为主少量业务代码开箱即用具备生产防护任务适配短流程Prompt任务、实验原型、轻量工具调用长周期复杂任务、代码执行、运维操作、政企/金融高合规场景多智能体模式仅提供通信与调度抽象协作规则自己写内置分布式集群、A2A协议、任务委派、批量协同调度能力迭代评估无内置自动评估体系需额外集成第三方工具自带评估打分、错误回放、策略对比实验能力典型产出可二次改造的Agent代码片段、业务逻辑模块可直接部署运行的独立Agent服务实例1.4 主流开源 Harness 框架主流开源AI Harness框架对比表框架名称开发主体原生Harness实现开发语言核心定位Harness核心能力模型兼容性多智能体能力开源协议适用场景AgentScope阿里通义实验室完整内置HarnessAgent九大子系统Python/Java/TS企业级分布式智能体驾驭运行底座Docker沙箱、Workspace工作区、双层记忆压缩、会话持久、细粒度权限、生命周期钩子、子Agent调度、故障断点续跑、人在回路审批通义、GPT、Claude、DeepSeek、Ollama全兼容Actor分布式集群、超大批量多Agent协同、A2A/MCP协议Apache 2.0政企大规模SRE、数据智能、业务多角色协作、国产化生产部署OpenHarnessHKU香港大学数据系统实验室原生轻量化纯Harness运行时Python极简透明学术/自研驾驭底座43内置工具、多级权限、MEMORY.md持久、流式工具循环、后台任务、基础沙箱隔离所有OpenAI兼容本地/云端模型轻量子Agent集群、任务委派MIT算法研究、自定义深度改造、个人本地代码Agent、轻量工具智能体DeepAgentsLangChain官方基于LangGraph封装标准Harness层PythonLangChain生态专属生产驾驭壳图状态快照、重试校验、HITL人工拦截、上下文自动裁剪、基础安全围栏、评估回调钩子适配全部LangChain接入模型子Agent嵌套、串行/并行任务编排MIT存量LangChain项目快速生产化改造、通用业务单/多AgentHarbor Framework学术社区Terminal-Bench配套评测专用标准化Harness运行时PythonAgent批量基准评测驾驭平台统一执行管道、变量约束控制、批量打分回放、策略对比实验环境、无业务侵入沙箱通用LLM接口标准化接入仅评测场景轻量化多AgentMITAgent性能对比实验、Harness调参对照、学术基准测试ClawAegis蚂蚁集团清华安全增强型Harness插件层无独立RuntimePython/Java第三方安全防护Harness组件高危命令拦截、文件操作白名单、数据泄露检测、操作审计日志、无侵入挂载各类Agent框架适配所有主流Agent运行时跟随宿主框架多Agent能力Apache 2.0金融等高合规场景安全加固、现有智能体安全补强2. AgentScope Harness 架构2.1 定位HarnessAgent是ReActAgent的一层薄包装把长期运行Agent必备的工程能力打包进单一Builder。裸的ReActAgent只解决”一次请求 → 推理 → 工具 → 回复”Harness在此基础上回答下一轮怎么接着上一轮上下文如何保持有界多用户如何隔离危险操作如何先 review 再执行可复用能力如何沉淀2.2 核心工作原理原则一能力叠加在推理循环的关键时机上不改写循环。工作区注入、对话压缩、子Agent、沙箱、Plan Mode—— 每个能力都通过Middleware钩在ReAct循环的关键时机上。core的推理算法本身不动Harness只在上面加东西。原则二能力之间互不依赖只通过三个共享对象通信。共享对象作用生命周期RuntimeContext本次call()的身份信息sessionId、userId、自定义extra不持久化单次调用工作区Workspace文件读写入口物理落到本机、沙箱还是 KV 存储由配置决定跨调用持久AgentStateStore跨调用恢复运行时状态跨调用持久按(userId, sessionId)寻址原则三内置 Middleware 注册顺序固定自定义 Middleware 跑在最前面。Harness在构建期按固定顺序串起所有内置Middleware。通过.middleware(...)添加的自定义Middleware会在Harness内置之前执行。2.3 核心能力一览每个能力对应一个具体问题按需在Builder上打开能力解决的问题Builder 入口工作区驱动的人格人格 / 知识 / 子 Agent / 技能 / MCP 白名单都以文件形式存在.workspace(path)状态持久化同(userId, sessionId)跨请求、跨进程、跨副本恢复默认开启.stateStore(...)替换实现双层长期记忆长会话中有价值的事实自动沉淀到MEMORY.md默认开启.memory(...)定制对话压缩保持上下文有界模型真正溢出时强制重试.compaction(...)大工具结果卸载超 80K 字符的工具结果落盘 占位符避免撑爆上下文.toolResultEviction(...)子 Agent 编排委派任务给子 Agent支持同步/后台自动反向通知.subagent(...)或workspace/subagents/可插拔文件系统本机 Shell / 共享存储 / 沙箱不改代码切换.filesystem(...)沙箱隔离文件与命令隔离跨调用恢复支持多副本部署.filesystem(new DockerFilesystemSpec()...)计划模式Plan Mode只读思考阶段 HITL 审批退出.enablePlanMode()技能装配技能来源Git / Nacos / MySQL / classpath / 工作区.skillRepository(...)MCP 集成与工具白名单声明式 MCP Server 工具粒度允许/拒绝workspace/tools.jsonChannel 路由会话管理、per-session 并发控制、多 Agent 路由、流式事件agent.channel(...)/GatewayBootstrap2.4 状态流转状态分三层框架自动在层之间搬数据第一层调用内状态AgentState对话上下文、权限规则、Plan Mode状态、工具状态RuntimeContextsessionId、userId、沙箱句柄、extra第二层跨调用状态每次call()结束自动写盘下次自动加载AgentState运行时快照 →AgentStateStore默认~/.agentscope/state/agentId/对话日志 →sessions/sessionId.log.jsonl永不压缩子任务记录、沙箱元数据第三层长期记忆跨Session累积memory/YYYY-MM-DD.md每日只追加后台节流任务周期性合并到MEMORY.mdMEMORY.md每轮推理被注入system prompt三个关键规律System prompt每轮重新拼修改AGENTS.md或MEMORY.md立刻生效无需重启。压缩、记忆提炼、后台维护都由节流闸门控制不会每轮都跑。AgentState由core的ReActAgentAgentStateStore自动持久化Harness不额外处理。2.5 自定义 Middleware 注意事项在Harness环境下添加自定义Middleware时使用.middleware(...)注册自定义Middleware会在所有Harness内置之前执行。通过agent.getRuntimeContext()读取当前调用的身份信息userId/sessionId不要在Middleware实例字段中缓存请求级状态。读写工作区使用harnessAgent.getWorkspaceManager()它会按当前文件系统模式本机 / 沙箱 / 远端正确路由。直接使用java.nio.Files在沙箱或远端模式下会写入错误位置。3. 快速开始3.1 依赖dependencygroupIdio.agentscope/groupIdartifactIdagentscope/artifactIdversion2.0.0-RC2/version/dependencydependencygroupIdio.agentscope/groupIdartifactIdagentscope-harness/artifactIdversion2.0.0-RC2/version/dependency3.2 最小示例importio.agentscope.harness.agent.HarnessAgent;importio.agentscope.core.model.DashScopeChatModel;importio.agentscope.core.message.*;// 1. 创建模型varmodelDashScopeChatModel.builder().apiKey(System.getenv(DASHSCOPE_API_KEY)).modelName(qwen-plus).build();// 2. 构建 HarnessAgent本地工作区varagentHarnessAgent.builder().name(my-first-agent).model(model).sysPrompt(你是一个有用的 AI 助手用中文回答。).workspace(Paths.get(.agentscope/workspace)).build();// 3. 调用varmsgMsg.builder().role(MsgRole.USER).content(List.of(TextBlock.builder().text(你好介绍一下你自己).build())).build();varreplyagent.call(List.of(msg)).block();System.out.println(reply.getTextContent());运行后自动创建的目录结构.agentscope/workspace/ ├── AGENTS.md ← 你的 sysPrompt 自动写入 ├── MEMORY.md ← 长期记忆跨会话累积 ├── memory/ ← 日流水账 memory/YYYY-MM-DD.md ├── skills/ ← 技能目录 ├── subagents/ ← 子 Agent 声明 ├── agents/id/sessions/ ← 会话日志 └── plans/ ← Plan Mode 计划文件3.4 带工具 多轮对话importio.agentscope.core.tool.Toolkit;importio.agentscope.core.agent.RuntimeContext;// 注册工具varweatherToolnewWeatherTool();// 标注 Tool 的 BeanvartoolkitnewToolkit();toolkit.registerTool(weatherTool);varagentHarnessAgent.builder().name(weather-assistant).model(model).toolkit(toolkit).sysPrompt(你是一个天气助手使用工具回答天气问题。用中文回复。).workspace(Paths.get(.agentscope/workspace/weather)).build();// 多轮对话varctxRuntimeContext.builder().sessionId(session-001).userId(alice).build();// 第一轮agent.call(List.of(userMsg(北京天气)),ctx).block();// 第二轮 —— 自动从 stateStore 加载上一轮的对话历史agent.call(List.of(userMsg(上海呢)),ctx).block();3.5 三种文件系统模式// 模式 1本地文件系统默认无需配置varagentHarnessAgent.builder().name(local-agent).model(model).workspace(Paths.get(./my-workspace)).build();// 模式 2Docker 沙箱隔离执行varagentHarnessAgent.builder().name(sandbox-agent).model(model).workspace(Paths.get(./ws)).filesystem(newDockerFilesystemSpec()// ← 一行切换.image(agentscope/sandbox:latest)).isolationScope(IsolationScope.USER).build();// 模式 3远程共享存储多副本varagentHarnessAgent.builder().name(distributed-agent).model(model).workspace(Paths.get(./ws)).filesystem(newRemoteFilesystemSpec(store))// ← Redis/JDBC 共享.distributedStore(RedisDistributedStore.fromJedis(jedis)).build();3.6 技能SkillvaragentHarnessAgent.builder().name(skill-agent).model(model).toolkit(toolkit).workspace(Paths.get(./ws))// 从本地目录加载 skill.skillRepository(newFileSystemSkillRepository(Paths.get(./skills)))// 从 Git 加载 skill.skillRepository(newGitSkillRepository(https://github.com/org/skills.git)).build();3.7 Spring Boot 完整示例ConfigurationpublicclassHarnessConfig{BeanpublicModelmodel(){returnDashScopeChatModel.builder().apiKey(System.getenv(DASHSCOPE_API_KEY)).modelName(qwen-plus).build();}BeanpublicHarnessAgentagent(Modelmodel,WeatherToolweatherTool){PathwsPaths.get(System.getProperty(user.home),.agentscope,workspace,demo);try{Files.createDirectories(ws);}catch(Exceptionignored){}returnHarnessAgent.builder().name(demo-agent).model(model).toolkit(registerTools(weatherTool)).sysPrompt(你是一个 AI 助手可以用中文回答使用工具获取信息。).workspace(ws).build();}privateToolkitregisterTools(WeatherToolweatherTool){ToolkittknewToolkit();tk.registerTool(weatherTool);returntk;}}RestControllerRequestMapping(/agent)publicclassAgentController{privatefinalHarnessAgentagent;GetMapping(/call)publicMonoMapString,Objectcall(RequestParamStringquery,RequestParam(defaultValuedemo)Stringuid){varctxRuntimeContext.builder().sessionId(s-System.currentTimeMillis()).userId(uid).build();varmsgMsg.builder().role(USER).content(List.of(TextBlock.builder().text(query).build())).build();returnagent.call(List.of(msg),ctx).map(r-Map.of(response,r.getTextContent()));}}