AgentScopeJavav2中Harness架构解析，13个中间件如何默认加载与分工

在 AgentScope Java v2 框架中，一个看似“空”的 HarnessAgent 实际已内置丰富能力。当开发者仅调用 HarnessAgent.builder().name("anatomy-probe").model(new FakeChatModel()).build() 创建代理实例时，系统自动装配了13个中间件与23个工具，并将状态持久化至本地目录——这一现象颠覆了“按需启用”的常规预期，转而采用“默认全装、显式裁剪”的工程策略。

该行为可通过 /workbench/harness/anatomy 端点验证：返回结构清晰列出 middlewares（13项）、tools（23项）与 stateStore（JsonFileAgentStateStore 实例）。其中13个中间件构成包括1个核心中间件、1个用户自定义中间件（如示例中的 ProbeUserMiddleware），以及11个由 Harness 自动注入的中间件。值得注意的是，这13项并非直接对应官方文档所述的“十二项能力”，二者映射关系需进一步解构。

Harness 的定位：模型之外的确定性工程层

Harness 并非推理引擎本身，而是围绕 Agent Loop 构建的工程系统。其官方定义强调：“Harness = 模型之外、围绕 Agent Loop 组织上下文、能力、状态、环境与控制机制，并把模型判断转化为可执行、可恢复、可验证任务过程的代码 / 配置 / 执行逻辑。” 关键在于“模型之外”四字——所有逻辑均由 Java 代码实现，不依赖提示词长度或模型权重。

例如，上下文溢出问题无法靠扩充提示词解决，真正起作用的是 CompactionMiddleware 对事件流进行截断与摘要；权限校验、错误重试、计划验证等确定性流程，也均在模型生成之外完成。这意味着，即使使用 FakeChatModel 占位模型，Harness 仍能完整执行其控制逻辑链。

从架构层级看，Harness 与 Runtime、Sandbox 明确分工：

• Harness 决定“模型看到什么、能调用哪些工具”；
• Runtime 负责进程调度、队列管理与并发控制；
• Sandbox 管理文件访问、网络限制与子进程隔离。

这种分层使 Agent 系统具备可测试性与可恢复性——例如，一次失败的工具调用可在 Harness 层触发回滚，而无需重新生成整个对话历史。

13个中间件的来源与动态性

13个中间件并非静态硬编码，而是由三类来源组合而成：

这些中间件按 order 排序形成责任链，环绕整个 ReAct 循环。关键观察是：部分能力（如“双层长期记忆”“大结果卸载”）虽被列为独立功能，却共享同一中间件实现，因此12项能力 ≠ 12个中间件。图2表格清晰展示了能力与中间件的非一一映射关系：

例如，“对话压缩”与“大结果卸载”均标记为“不拆（0010）”，说明它们由同一中间件处理；而“子代理编排”则横跨 §5.2 与 §5.3 两节，涉及多个中间件协同。

此外，中间件的激活具有条件性。例如，当配置启用沙箱隔离时，SandboxMiddleware 才会被注入；若未指定工作区路径，状态存储默认落至用户家目录（可通过 agentscope.state.home 环境变量重定向）。

状态管理：账本、Workspace 与 RuntimeContext 的分工

状态持久化是 Harness 的另一关键设计。默认使用 JsonFileAgentStateStore 将 Agent 运行时状态序列化至磁盘，确保重启后可恢复会话。但更精细的状态划分体现在三个层面：

• RuntimeContext：存放单次请求的上下文变量（如 sessionId、userId、extra 字段），不落盘，随请求生命周期消亡；
• Workspace：存储 Agent 的“人格”声明、技能清单、子代理配置等元数据，位于 ./workspace/ 目录下，以 .md 或 .json 形式组织；
• AgentStateStore：记录跨轮次状态变更（如工具调用结果、记忆摘要），支持跨会话恢复。

图3进一步说明三者职责边界：

例如，当 Agent 需要读写文件时，权限判断由 FilesystemMiddleware 在 RuntimeContext 中检查 userId 与 workspace 中声明的权限白名单；而实际文件操作则交由 Sandbox 执行。这种分离保障了安全性与可审计性。

与同类框架的差异：默认厚度与栈位置

当前主流 Agent 框架多采用轻量内核+插件扩展模式，而 AgentScope Harness 的独特之处在于其“出厂即满配”策略。对比其他方案：

• LangChain：核心链路精简，多数能力需手动集成工具与回调；
• LlamaIndex：聚焦检索增强，状态管理较弱；
• Microsoft Semantic Kernel：提供插件系统，但默认中间件数量有限。

AgentScope 则将权限控制、记忆管理、错误恢复、沙箱隔离等企业级能力前置集成，降低上手门槛，但也带来一定学习成本——开发者需理解哪些能力可关闭、哪些不可裁剪。

例如，ProbeUserMiddleware 的 order=50 表明其插入点位于核心中间件之后、Harness 自动中间件之前，便于调试与拦截。若需禁用某项能力（如对话压缩），需显式排除对应中间件，而非简单关闭开关。

工程启示：横切关注点归中间件，控制流归引擎

Harness 架构的核心哲学可概括为：“横切归中间件，控制流归引擎”。所有跨业务逻辑的通用能力（日志、监控、限流、压缩、持久化）应抽象为中间件；而决策路径（如是否调用子代理、何时终止循环）则由引擎层统一调度。

这种设计使 Agent 系统具备良好可观测性：通过分析中间件链执行顺序与耗时，可快速定位性能瓶颈；同时，因中间件独立于模型，升级或替换不影响核心推理逻辑。

目前，该架构已在网易内部多个智能体项目中落地，支撑包括合同审核、客服辅助、代码生成等场景。随着 v2.1 版本推进，官方计划开放中间件热插拔接口，允许运行时动态增删能力模块。

对于开发者而言，理解 Harness 的默认装配逻辑是高效定制的前提。与其从零搭建，不如先“解剖”一个空 Agent，看清13个中间件如何协同工作——这正是第9课设置 /anatomy 端点的初衷：让抽象架构变得可触、可验、可调。