Agent Harness 实战指南：构建生产级 AI Agent 的“马具“框架

hatModel 封装而是一个专门为 AI Agent 打造的生产级执行框架。官方定义说得好Agent Model Harness。模型提供推理Harness 提供落地执行的实体。如果说模型是 CPU上下文是内存那 Harness 就是操作系统——负责资源调度与环境隔离。solon-ai-harness 已经在 SolonCode CLI 项目中经过了多个月的实战验证本文带你从零上手。添加依赖org.noearsolon-ai-harness${solon.version}solon-ai-harness 同时支持 Java 8 到 Java 25兼容性不用担心。快速上手Hello World先来一个最简单的例子构建一个只拥有四个基础工具读、写、编辑、执行命令的 Agent让它帮我们完成一个任务。import org.noear.solon.ai.agent.AgentSession;import org.noear.solon.ai.agent.session.InMemoryAgentSession;import org.noear.solon.ai.agent.session.AgentSessionProvider;import org.noear.solon.ai.chat.ChatConfig;import org.noear.solon.ai.harness.HarnessEngine;import org.noear.solon.ai.harness.permission.ToolPermission;import java.util.Map;import java.util.concurrent.ConcurrentHashMap;public class DemoApp {public static void main(String[] arg) throws Throwable {// 会话提供者决定会话如何存储这里用内存实现AgentSessionProvider sessionProvider new AgentSessionProvider() {private final MapString, AgentSession sessionMap new ConcurrentHashMap();Override public AgentSession getSession(String instanceId) { return sessionMap.computeIfAbsent( instanceId, k - InMemoryAgentSession.of(k) ); } }; // 构建 Harness 引擎 HarnessEngine engine HarnessEngine.of(/data/work/, .tmp) .systemPrompt(你是一个 AI 助手请根据用户指令完成任务。) .sessionProvider(sessionProvider) .toolsAdd(ToolPermission.TOOL_PI) // 仅开放 read/write/edit/bash .modelAdd(new ChatConfig().then(slf - { slf.setApiUrl(https://api.deepseek.com); slf.setApiKey(sk-你的Key); slf.setModel(deepseek-chat); })) .build(); // 执行任务 engine.prompt(在当前目录下创建一个 README.md内容为 # Hello Harness) .call(); }}就这么简单。HarnessEngine.of(workspace, harnessHome) 的两个参数workspaceAgent 的当前工作目录文件读写、命令执行都以它为根harnessHome马具主目录会话、记忆、技能等运行态数据落在这里3. 核心配置详解HarnessEngine.Builder 提供了一整套配置项让你精细控制 Agent 的行为。3.1 基础配置HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).systemPrompt(“你是一个 AI 助手”) // 系统提示词.sessionWindowSize(8) // 会话历史窗口大小默认 8.compressionThreshold(30, 30_000) // 触发压缩30 条消息或 30000 token.maxTurns(20) // 最大循环步数默认 20.autoRethink(true) // 最大步数自动续航默认 true.modelRetries(3) // 模型重试次数默认 3.build();3.2 工具权限配置toolsAdd 和 disallowedToolsAdd 控制 Agent 可以调用哪些工具// 开放所有工具包括 bash、文件读写、网络搜索等.toolsAdd(ToolPermission.TOOL_ALL_FULL)// 或仅开放基础工具.toolsAdd(ToolPermission.TOOL_PI) // read, write, edit, bash// 或精细控制开放再禁用某些.toolsAdd(ToolPermission.TOOL_ALL_FULL).disallowedToolsAdd(ToolPermission.TOOL_BASH) // 禁止 bash 执行工具权限分为公域和私域公域read、write、edit、bash、websearch、webfetch、glob、grep、ls、skill、task 等私域generate生成子代理、高阶权限需人工确认3.3 沙盒安全配置HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).sandboxEnabled(true) // 启用沙盒模式.sandboxAllowUserHome(true) // 允许访问用户主目录.sandboxSystemRestrict(true) // 系统级限制危险操作需人工确认.build();沙盒模式下Agent 只能访问工作区和指定的挂载目录不能越界到系统目录。3.4 多模型配置.modelAdd(new ChatConfig().then(slf - {slf.setApiUrl(“https://api.deepseek.com”);slf.setApiKey(“sk-);slf.setModel(“deepseek-chat”);})).modelAdd(new ChatConfig().then(slf - {slf.setApiUrl(“https://api.openai.com/v1”);slf.setApiKey(sk-”);slf.setModel(“gpt-4o”);}))第一个添加的模型是主模型运行时可以通过 options() 动态切换。调用与流式响应engine.prompt(…) 返回的是一个 ReActRequest 接口支持同步和流式两种模式。4.1 同步调用engine.prompt(“帮我查一下当前目录有哪些 Java 文件”).call();4.2 流式响应适合需要实时展示 Agent 推理过程或逐步输出结果的场景engine.prompt(“分析当前项目的代码结构并生成文档”).stream();4.3 指定会话与请求选项// 获取或创建持久会话AgentSession session engine.getSession(“default”);engine.prompt(“帮我重构 UserService 类的逻辑”).session(session) // 绑定持久会话不指定则为临时会话.options(o - {// 切换大模型o.chatModel(engine.getModelOrMain(“gpt-4o”));// 动态指定工作区 o.toolContextPut(HarnessEngine.ATTR_CWD, /data/projects/myapp); }) .call();子代理与任务委派solon-ai-harness 内置了几个开箱即用的子代理名称 说明general 通用全能专家。其他子代理不匹配时用它explore 全域信息探索专家本地文件 全网检索无写权限plan 规划与计划专家制定逻辑路径与执行步骤bash Bash 命令执行专家git、命令行操作5.1 通过代码动态创建子代理AgentSession session engine.getSession(“default”);AgentDefinition definition new AgentDefinition();definition.setSystemPrompt(“你是一个 Git 专家负责执行仓库操作。”);definition.getMetadata().addTools(ToolPermission.TOOL_BASH);ReActAgent gitAgent engine.createSubagent(definition).build();gitAgent.prompt(“提交当前所有更改并推送”).session(session).call();5.2 通过 AgentManager 管理// 获取内置子代理AgentDefinition bashDef engine.getAgentManager().getAgent(“bash”);// 构建并执行ReActAgent bashAgent bashDef.builder(engine).build();bashAgent.prompt(“列出当前目录所有 Java 文件”).call();// 获取所有可用子代理Collection agents engine.getAgentManager().getAgents();// 动态注册自定义子代理engine.getAgentManager().addAgent(customDefinition);5.3 任务委派task / multitask主代理拥有 task 工具权限时可自主把子任务委派给子代理task(agentName, prompt)委派单一任务串行multitask([task1, task2, …])并行执行多个独立子任务子任务上下文隔离委派时必须在 prompt 中提供所有背景信息。会话与心智记忆会话保存单次对话的上下文心智记忆则在多次对话之间长期留存关键事实。6.1 会话提供者sessionProvider 是构建引擎的必填项// 自定义持久化如文件/数据库.sessionProvider(sessionId - {// 从数据库加载或创建会话return MyDatabase.loadSession(sessionId);})会话的运行态数据默认落在 {harnessHome}/sessions/ 下。6.2 心智记忆Memory心智记忆让 Agent 记住用户的偏好、项目规约等关键事实并在需要时检索召回。HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).memoryEnabled(true) // 默认开启.memoryProvider(new MemorySolutionProvider() {Overridepublic MemorySolution getSolution(String workspace) {// 每个工作区可以有不同的记忆方案return new MarkdownMemorySolution(workspace);}}).build();记忆方案内置 Markdown 实现零外部依赖也支持 Redis、Lucene、向量库等。Agent 可在运行中自主进行提取写入事实召回按 key 精确取语义检索自然语言检索认知整合碎片升维合并修剪删除过时认知7. 内置拦截器Harness 有三个内置拦截器负责保障 Agent 的稳定运行。7.1 上下文压缩拦截器防止上下文超出 Token 限制import org.noear.solon.ai.harness.interceptor.;import org.noear.solon.ai.harness.compression.;CompressionStrategy strategy new CompositeCompressionStrategy().addStrategy(new KeyInfoExtractionStrategy()) // 提取干货去水.addStrategy(new HierarchicalCompressionStrategy()); // 滚动更新摘要ContextCompressionInterceptor interceptor new ContextCompressionInterceptor(40, // 消息条数阈值60_000, // 内容长度阈值3, // 重试次数() - engine.getModelOrMain(engine.getCompressionModel()),strategy);HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).compressionInterceptor(interceptor).build();7.2 停止循环拦截器防止 Agent 陷入死循环StopLoopInterceptor stopLoop new StopLoopInterceptor(5, 10);// 5 次相同错误 / 10 轮窗口内触发停止HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).stopLoopInterceptor(stopLoop).build();7.3 HITL 人工介入拦截器对高危操作进行人工确认engine.setHitlEnabled(true);HITLInterceptor hitl new HITLInterceptor();hitl.onTool(“bash”, new HitlStrategy()); // bash 命令需要人工确认hitl.onTool(“write”, new WriteAuditStrategy()); // 写入操作审计HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).hitlInterceptor(hitl).hitlEnabled(true).build();7.4 自定义拦截器HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).extensionAdd((agentName, agentBuilder) - {agentBuilder.defaultInterceptorAdd(new ReActInterceptor() {Overridepublic void onAgentStart(ReActTrace trace) {System.out.println(“Agent agentName 开始执行traceId” trace.getTraceId());}});}).build();8. 扩展定制8.1 注册 OpenAPI 接口让 Agent 调用外部业务系统的 REST APIengine.addApiServer(new ApiSource().then(s - {s.setDocUrl(“http://xx.xx.xx/v3/api-docs”); // Swagger/OpenAPI 文档地址s.setApiBaseUrl(“http://xx.xx.xx/”);}));8.2 注册自定义工具HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).extensionAdd((agentName, agentBuilder) - {// 注册自定义业务工具agentBuilder.defaultToolAdd(new OrderQueryTool());agentBuilder.defaultToolAdd(new InventoryCheckTool());}).build();8.3 动态系统提示词HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).extensionAdd((agentName, agentBuilder) - {if (“main”.equals(agentName)) {agentBuilder.systemPrompt(context - {String project context.get(“projectName”);return “你是 project 项目的 AI 助手请严格遵循项目规范。”;});}}).build();// 也可以在运行时动态修改engine.setSystemPrompt(“新的系统提示词”);8.4 Prompt Caching对于支持缓存的大模型如 Anthropic Claude可以减少重复计算HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).cacheControl(CacheControl.of(CacheControl.Type.EPHEMERAL, // 临时缓存“user”, 60_000 // 用户的最后一条消息缓存 60 秒)).build();9. 目录结构与挂载机制马具主目录harnessHome按用途划分子目录子目录 用途sessions/ 会话与任务清单持久化skills/ 技能SKILL.mdagents/ 子代理定义Markdowncommands/ 自定义命令memory/ 心智记忆download/ 下载缓存除了内置目录还可以通过挂载把外部目录接入马具HarnessEngine engine HarnessEngine.of(“work”, “.soloncode/”).mountAdd(MountDir.builder().alias(“team-agents”) // 别名须以 开头.type(MountType.AGENTS) // 挂载类型.path(“~/team/agents/”) // 物理路径.primary(true) // 原始挂载不可删除.writeable(false) // 只读.build()).mountAdd(MountDir.builder().alias(“global-skills”).type(MountType.SKILLS).path(“~/.soloncode/skills/”).build()).build();挂载后可通过别名直接引用team-agents/code-reviewer.mdHarness 自动转换为真实路径。运行时动态管理engine.addMount(mountDir); // 添加挂载engine.hasMount(“team-agents”); // 是否存在engine.refreshMount(“team-agents”); // 重新扫描engine.removeMount(“team-agents”); // 移除primary 不可移除engine.getMounts(); // 所有挂载engine.getAgents(); // 所有子代理engine.getSkills(); // 所有技能10. 完整实战代码审查 Agent下面是一个完整的例子结合了本节介绍的大部分特性import org.noear.solon.ai.agent.AgentSession;import org.noear.solon.ai.agent.session.InMemoryAgentSession;import org.noear.solon.ai.agent.session.AgentSessionProvider;import org.noear.solon.ai.chat.ChatConfig;import org.noear.solon.ai.harness.HarnessEngine;import org.noear.solon.ai.harness.permission.ToolPermission;import java.util.Map;import java.util.concurrent.ConcurrentHashMap;public class CodeReviewApp {public static void main(String[] arg) throws Throwable {AgentSessionProvider sessionProvider new AgentSessionProvider() {private final MapString, AgentSession sessionMap new ConcurrentHashMap();Overridepublic AgentSession getSession(String instanceId) {return sessionMap.computeIfAbsent(instanceId, k - InMemoryAgentSession.of(k));}};HarnessEngine engine HarnessEngine.of(/data/projects/myapp, .soloncode/) .systemPrompt(你是一个资深代码审查专家负责分析代码质量。) .sessionProvider(sessionProvider) .sessionWindowSize(12) .compressionThreshold(50, 40_000) .maxTurns(30) .autoRethink(true) .toolsAdd(ToolPermission.TOOL_PI) // read, write, edit, bash .modelAdd(new ChatConfig().then(slf - { slf.setApiUrl(https://api.deepseek.com); slf.setApiKey(sk-***); slf.setModel(deepseek-chat); })) .sandboxEnabled(true) .build(); // 第一次对话审查代码 AgentSession session engine.getSession(review-001); engine.prompt(审查 src/main/java/com/example/UserService.java 检查潜在问题并输出审查报告到 code-review.md) .session(session) .call(); // 第二次对话基于历史修复问题 engine.prompt(根据刚才生成的审查报告修复代码中的问题) .session(session) .call(); }}总结solon-ai-harness 提供了一套从能思考到能干活的完整基础设施。它的核心能力可以概括为四个维度组织工具使用 — 权限控制、MCP 协议、输入输出标准化管理记忆与会话 — 持久化、上下文压缩、心智记忆环境隔离与安全 — 沙盒模式、HITL 人工确认、循环检测生态扩展 — OpenAPI 接入、自定义工具、挂载机制