重新认识 AgentScope-Java 2.0ReActAgent 负责推理HarnessAgent 负责运行AgentScope-Java 2.0.0-RC4TUTORIALPROJECT这篇文章的读法先跑通再解释先验收再扩展。很多 Java 开发者第一次接触 Agent 框架走的是同一条路接入模型写 Prompt注册几个 Tool再让 ReAct 循环跑起来。这条路没有错。问题是如果继续用它理解 AgentScope-Java 2.0很容易把框架看窄只盯着 agent.call() 怎么写、支持哪些模型、工具怎么声明却忽略了一个 Agent 真正进入系统以后还要面对什么。我的判断是AgentScope-Java 2.0 的定位已经从“构建一个 ReAct Agent”上移到了“运行和治理生产级 Agent”。ReActAgent 仍然是推理内核负责模型、消息、工具和推理循环HarnessAgent 则把工作区、记忆、计划、权限、子 Agent、沙箱和状态恢复组织到一起成为面向真实应用的工程入口。换句话说AgentScope-Java 2.0 不只关心 Agent 会不会调用工具。它开始回答另一组更麻烦的问题这个 Agent 以什么身份运行文件放在哪里状态如何保存子 Agent 能继承哪些权限任务中断以后怎么恢复这才是理解 2.0 的主线。01PART如果还停留在 ReAct看到的只是推理内核SETUP · 准备上下文把 Agent 简化成下面这条链路是很自然的...text模型 Prompt Tool ReAct 循环提示长代码可向右滑动查看。这套结构解决的是“Agent 如何完成一次任务”。模型负责判断下一步Tool 连接外部能力ReAct 循环在推理、行动和观察之间不断推进直到返回结果。在 AgentScope-Java 2.0 里这部分能力没有消失。ReActAgent 仍然承担核心推理工作。如果你的需求只是一个短生命周期、边界简单的工具调用 Agent官方 README 也明确说明可以只依赖 agentscope-core直接使用裸 ReActAgent。但一次调用跑通不代表 Agent 已经能进入真实应用。只要任务开始跨越多个用户、多个会话或者多轮执行新的问题马上会出现两个用户同时调用同一个 Agent状态会不会串工具生成的报告、计划和临时文件应该放在哪里Agent 重启以后上一轮任务从哪里继续子 Agent 被委派出去以后能不能绕过父 Agent 的权限边界一个任务取消了事件流、状态和后台执行是否真的结束这些问题都不属于 ReAct 算法本身却决定了 Agent 能不能长期运行。02PARTHarnessAgent 为什么成了 2.0 的工程入口CODE · 最小实现当前中文 README 的 Maven 快速开始首先引入的是...xmldependencygroupIdio.agentscope/groupIdartifactIdagentscope-harness/artifactIdversion2.0.0/version/dependency提示长代码可向右滑动查看。第一个示例创建的也不是裸 ReActAgent而是 HarnessAgent...javaHarnessAgent agent HarnessAgent.builder().name(assistant).sysPrompt(你是一个有用的 AI 助手。).model(dashscope:qwen-plus).workspace(Paths.get(.agentscope/workspace)).build();RuntimeContext ctx RuntimeContext.builder().sessionId(demo).userId(alice).build();agent.call(new UserMessage(你好), ctx).block();提示长代码可向右滑动查看。这段代码表面上仍然是创建 Agent、传入消息、获取结果但多了两个不该被忽略的对象Workspace 和 RuntimeContext。它们说明这次调用不再发生在一个抽象的推理循环里而是属于具体用户、具体会话和具体工作空间。从源码关系看HarnessAgent 并没有继承 ReActAgent。它实现 Agent 接口内部持有一个 ReActAgent delegate再通过 Middleware、Toolkit 和各类 Manager 叠加工程能力。所以“薄包装”这个说法只适用于它和推理内核的组合关系不能理解成它承担的工作很少。恰恰相反HarnessAgent 增加的都是 Agent 进入真实系统后最难补的部分基于 Workspace 加载 AGENTS.md、MEMORY.md、知识、技能和子 Agent 定义在本地文件系统、共享存储和沙箱之间切换进行上下文压缩和大工具结果卸载支持 Plan Mode同步或后台委派子 Agent装配 MCP Server 和工具白名单管理多会话状态、恢复与并发。可以把两者的分工简单理解为层次核心对象主要回答的问题推理内核ReActAgentAgent 怎么理解消息、调用工具并完成任务工程入口HarnessAgentAgent 怎么带着身份、状态、文件和权限长期运行AgentScope-Java 2.0 的变化不是把前一层替换掉而是在前一层之上补齐了运行环境。03PART三个对象划清 Agent 的运行边界VERIFY · 验收结果理解 AgentScope-Java 2.0最关键的不是记住所有 Builder 配置而是先分清 RuntimeContext、AgentState 和 Workspace。RuntimeContext谁在发起这次调用RuntimeContext 是每次调用的运行上下文核心标识是 userId 和 sessionId。HarnessAgent 自身在调用之间不保存用户状态可以作为单例服务多个用户和会话。真正的隔离依据来自本次调用传入的 (userId, sessionId)同一会话的调用会串行执行不同会话可以并行。这和在 Controller 里直接复用一个有状态 Agent 完全不同。多用户服务不能依赖默认 session也不应该把当前用户藏在一个全局变量里。身份必须跟着每次调用显式进入运行上下文。AgentState任务运行到了哪里AgentState 保存的是运行快照例如对话缓冲和摘要当前迭代位置工具上下文权限上下文子任务状态Plan Mode 上下文中断标记。AgentStateStore 负责保存和恢复这些状态。它处理的是“这次任务跑到了哪里”而不是业务系统里所有需要持久化的数据。例如代码评审系统里的 ReviewJob、审批状态和发布记录仍然应该属于业务领域不能因为框架提供了 AgentState就把业务数据库全部塞进去。WorkspaceAgent 长期留下了什么Workspace 保存的是跨调用可复用的文件和 Agent 定义例如...textAGENTS.mdMEMORY.mdmemory/skills/subagents/plans/会话日志任务报告提示长代码可向右滑动查看。计划文件、生成报告、长期记忆和技能都更接近 Workspace 产物而不是一次调用的内存状态。这三个对象合在一起形成了 AgentScope-Java 2.0 的运行模型...textRuntimeContext谁在运行AgentState任务运行到了哪里Workspace任务长期留下了什么提示长代码可向右滑动查看。如果这三个边界没有分清后面的分布式状态、权限和恢复都会混在一起。04PARTPlan Mode 管的不只是计划而是执行阶段SUMMARY · 下一步旧版 PlanNotebook 容易让人把计划理解成一个记录任务清单的组件。当前源码已经删除了这套 API替代它的是 HarnessAgent.builder().enablePlanMode()。这不是一次同构替换。Plan Mode 先让 Agent 进入只读调查阶段。它可以读取资料、分析问题并通过 plan_write 更新计划文件但不能直接执行修改。当计划完成后plan_exit 再通过 ASK / HITL 权限流程请求进入执行阶段。这里同时存在两种状态计划文件写入 Workspace成为可检查、可保留的任务产物当前是否处于 Plan Mode写入 AgentState.planModeContext属于运行状态。这正好体现了前面的分层计划内容和执行阶段不是一回事。Plan Mode 还会影响子 Agent。7 月底的源码已经实现父 Agent 处于 Plan Mode 时由 Harness 自动构建和复用的本地子 Agent 也会进入对应的计划阶段父级的 DENY 权限规则会合并到子 Agent 对应的用户和会话槽位。这条规则很重要。多 Agent 协作最危险的情况不是主 Agent 明着越权而是它把任务委派出去以后子 Agent 获得了更大的能力。当前仓库的 plan-mode.md 仍保留一处“子 Agent 不自动继承”的旧说明但 subagent.md、实现代码和回归测试已经指向继承行为。涉及权限边界时应以当前源码和测试为准。05PART权限和沙箱解决的是 Agent 能走多远DETAIL · 继续推进工具注册解决“Agent 能做什么”权限系统解决“这一次允许它做到哪一步”。在 AgentScope-Java 2.0 里权限边界已经覆盖工具允许与拒绝Plan Mode 的只读限制从计划进入执行的人工确认父 Agent DENY 规则向子 Agent 继承Workspace 的用户和会话隔离本地、Docker、Kubernetes、E2B 等文件系统或沙箱后端。源码还在路径层做了额外防护。AbstractFilesystem.validatePath()、LocalFilesystem.resolveRooted() 和 WorkspaceManager 会拒绝包含 .. 段的路径穿越并验证解析后的路径仍处于工作区根目录内。启用用户命名空间时也不能借路径逃逸到其他用户目录。这并不意味着业务系统可以删除自己的安全检查。框架知道的是 Workspace、Tool 和 Sandbox 的边界业务系统知道的则是“这个用户能不能评审这个仓库”“这份报告能不能发布”“这个审批能不能跳过”。两层防线解决的是不同问题应该叠加而不是互相替代。06PART真正暴露框架定位的是那些 Demo 看不到的问题DETAIL · 继续推进从 RC4 到当前源码最能说明 AgentScope-Java 2.0 定位的不是增加了多少模型和 Starter而是近期修复集中在哪里。这些提交反复处理的是用户中断或应用关闭时保存状态短生命周期 Agent 关闭后解除状态保存器避免资源累积连续上下文压缩时保留上一轮摘要避免用户意图丢失异步子 Agent 被取消后正确关闭事件流流式工具参数为 null、文本 delta 丢失和模型 SSE 错误体丢失Windows shell、工作区路径和异常 Unicode 状态文件兼容沙箱快照、跨节点恢复和分布式执行锁。这些问题不会出现在最简单的 Hello World 里。Demo 只需要证明 Agent 能给出答案真实系统却要保证它被取消后真的停止、重启后能够恢复、多个副本不会重复执行、上下文压缩后仍然记得用户要做什么。所以AgentScope-Java 2.0 的价值越靠近生产环境越体现在 ReAct 循环之外。07PART从 RC4 走过来的项目不需要推倒重来DETAIL · 继续推进框架主入口变化不等于以前基于 ReActAgent 写的项目全部失效。以现有 Review Copilot代码评审助手 系列为例RC4 阶段建立的业务结构仍然成立只是放到当前 2.0 里需要重新划分责任RC4 项目中的做法放到当前 AgentScope-Java 2.0 中怎么理解AgentFactory封装 ReActAgent短任务仍可保留长期运行场景再评估上移到 HarnessAgent自建 SSE 进度事件业务事件继续保留框架执行过程优先接 streamEvents()手工只读路径守卫继续作为业务防线框架层再叠加 Workspace、Permission 和 SandboxModelFactory隔离模型提供商继续保留模型 artifact、兼容协议和语义 formatter 是不同层次Middleware 记录审计信息继续保留并补充 RuntimeContext、session 和子 Agent 来源ReviewJob和 Markdown 报告ReviewJob属于业务状态报告更接近 Workspace 的持久产物迁移的重点不是把所有 ReActAgent 换成 HarnessAgent而是先问清楚现有项目里哪些代码在处理推理哪些代码在处理运行环境哪些又是不能交给框架的业务规则。边界清楚以后才知道哪些能力应该保留哪些重复建设可以交还给 Harness。08PART重新安排 AgentScope-Java 2.0 的学习顺序DETAIL · 继续推进如果仍然按照“模型接入—Prompt—Tool Calling—ReAct”一路学到底很容易在最熟悉的地方停下来。更适合 2.0 的学习顺序是1. 用 ReActAgent 理解消息、模型、工具和推理循环 2. 用 HarnessAgent 理解 AgentScope-Java 2.0 的工程入口 3. 分清 RuntimeContext、AgentState 和 Workspace 4. 再进入 Plan Mode、Permission、Sandbox 和子 Agent 5. 最后处理状态恢复、沙箱快照和分布式执行。这条顺序没有否定 ReAct。它只是把 ReAct 放回了正确的位置推理内核而不是生产级 Agent 的全部。09PART什么情况下值得了解 AgentScope-Java 2.0DETAIL · 继续推进如果你只想写一个短生命周期、边界简单的工具调用 Agent直接使用 ReActAgent 就够了。甚至在很多业务里一个清晰的工作流加几次模型调用比引入完整的 Harness 更合适。但如果你想尝试搭建一个 Java 版多 Agent 协作平台可以去了解一下 AgentScope-Java 2.0。重点不要只看 agent.call()而要看 HarnessAgent 如何组织 Workspace、Plan Mode、子 Agent、权限和状态恢复。这些能力正好对应多 Agent 平台最早会遇到的任务协作、权限继承、过程留痕和失败恢复问题。它不会替你完成所有业务设计也不会自动解决多 Agent 协作中的任务划分和结果质量问题但能提供一套现成的 Agent 运行底座。这才是 AgentScope-Java 2.0 更值得关注的地方。