一、引言Agent 是框架的心脏在 AgentScope Java 2.0 的八大构建块Building Blocks中Agent是最核心的一块——它是整个框架的发动机。官方文档明确指出ReActAgent 提供 Agent Loop 抽象与所有底层原子能力HarnessAgent 提供保障效果、稳定、分布式部署、长期运行的一站式解决方案。本文系统解析 AgentScope Java 2.0 中 Agent 构建块的设计哲学、核心 API、执行模型与工程化实践。二、双层 Agent 架构ReActAgent 与 HarnessAgent2.1 架构关系AgentScope Java 2.0 的 Agent 层采用双层架构设计┌──────────────────────────────────────────────────────┐ │ HarnessAgent │ │ ┌────────────────────────────────────────────────┐ │ │ │ ReActAgent核心推理引擎 │ │ │ │ 一次请求 → 推理 → 工具调用 → 观察 → 回复 │ │ │ └────────────────────────────────────────────────┘ │ │ Workspace 记忆压缩 Session持久化 │ │ 子Agent 沙箱隔离 计划模式 │ └──────────────────────────────────────────────────────┘HarnessAgent 是 ReActAgent 的一层薄包装把长期运行 Agent 必备的工程能力打包进单一 Builder。层级类名定位适用场景核心层ReActAgentAgent Loop 抽象 底层原子能力原型验证、单次请求工程层HarnessAgent生产就绪的一站式方案推荐入口企业级部署、长期运行关键设计原则不开任何额外能力时HarnessAgent 的行为等价于裸 ReActAgent。开发者可以从 ReActAgent 起步做原型生产迁移时通过 Builder 无缝切换到 HarnessAgent业务代码无需任何改动。2.2 类继承体系Agent接口 └── AgentBase抽象基类 └── ReActAgent核心推理引擎 └── HarnessAgent工程化包装2.0 新增这种设计让框架既保证了灵活性又提供了统一的基础能力。三、ReActAgent核心推理循环3.1 ReAct 范式ReActReasoning Acting是 AgentScope 的核心推理范式。Agent 交替进行推理和行动用户输入 ↓ ┌─────────────────────────────────┐ │ 思考Reasoning │ ← 模型推理决定下一步 │ ↓ │ │ 行动Acting │ ← 调用工具执行操作 │ ↓ │ │ 观察Observing │ ← 获取工具执行结果 │ ↓ │ │ 判断是否需要继续 │ │ 是 → 回到思考 │ │ 否 → 输出最终回复 │ └─────────────────────────────────┘ ↓ 最终回复3.2 Builder 构建参数ReActAgent 通过 Builder 模式创建关键参数如下ReActAgentagentReActAgent.builder().name(assistant)// Agent 名称.sysPrompt(你是一个有帮助的 AI 助手。)// 系统提示词.model(dashscope:qwen-plus)// 模型字符串由 ModelRegistry 解析.maxIterations(10)// 最大推理轮数防止无限循环.toolkit(toolkit)// 注册的工具集.middleware(middlewareChain)// 中间件链2.0 新特性.build();参数类型说明nameStringAgent 标识名称sysPromptString系统提示词定义 Agent 角色与行为边界modelString / Model模型配置支持字符串简写或 Model 实例maxIterationsint最大推理轮数防止无限循环安全阀toolkitToolkit注册的工具集合middlewareList中间件链2.0 替代 Hook3.3 模型配置字符串简写AgentScope 2.0 支持以字符串形式指定模型由 ModelRegistry 自动解析并读取对应环境变量.model(dashscope:qwen-plus)// 读取 DASHSCOPE_API_KEY.model(openai:gpt-5.5)// 读取 OPENAI_API_KEY.model(anthropic:claude-sonnet-4-5)// 读取 ANTHROPIC_API_KEY.model(gemini:gemini-2.0-flash)// 读取 GEMINI_API_KEY.model(ollama:llama3)// 本地 Ollama 模型同时支持主备模型链FallbackModel主模型调用失败时自动切换备用模型保证长链路任务不中断。3.4 工具注册Tool 注解使用 Tool 注解将任意 Java 方法注册为 Agent 可调用的能力importio.agentscope.core.tool.Tool;importio.agentscope.core.tool.ToolParam;publicclassWeatherTools{Tool(description查询指定城市的天气)publicStringgetWeather(ToolParam(description城市名称)Stringcity,ToolParam(description日期格式 yyyy-MM-dd)Stringdate){// 实际查询逻辑return晴天25°C;}}四、三大调用模式call / streamEvents / observeAgentScope 2.0 提供三种调用方式覆盖不同交互场景4.1 call() —— 同步调用返回 Mono适合请求-响应模式Msgresponseagent.call(newUserMessage(帮我查一下北京今天的天气),RuntimeContext.builder().sessionId(session-001).userId(alice).build()).block();4.2 streamEvents() —— 流式事件返回 Flux适合 Web/TUI 实时渲染agent.streamEvents(newUserMessage(用三句话介绍 AgentScope Java)).doOnNext(event-{if(eventinstanceofTextDeltaEventdelta){// 边生成边输出System.out.print(delta.getDelta());}elseif(eventinstanceofToolCallStartEventtoolCall){System.out.println(\n[tool] toolCall.getToolCallName());}}).blockLast();框架提供 28 种类型化事件覆盖完整的推理-行动生命周期事件类别典型事件用途文本生成TextDeltaEvent流式文本输出推理过程ThinkingBlockEvent模型思考过程工具调用ToolCallStartEvent工具开始执行工具结果ToolResultEvent工具返回结果生命周期ReplyFinishEvent本轮回复结束4.3 observe() —— 静默观察将消息注入 Agent 上下文但不触发回复适用于多 Agent 协作中的信息同步agent.observe(newUserMessage(这是来自其他 Agent 的通知...));五、Middleware2.0 的核心扩展机制5.1 从 Hook 到 MiddlewareAgentScope 2.0废弃了 1.x 的扁平 Hook 机制替换为结构化的 Middleware 体系。五个明确阶段取代了原来松散的回调publicinterfaceMiddleware{voidonAgent(AgentContextctx);// Agent 生命周期voidonReasoning(ReasoningContextctx);// 推理阶段voidonActing(ActingContextctx);// 行动阶段voidonModelCall(ModelCallContextctx);// 模型调用voidonSystemPrompt(PromptContextctx);// 系统提示词构建}5.2 设计优势对比维度1.x Hook2.0 Middleware粒度扁平、无阶段区分五个明确阶段关注点混杂在一起各居其层组合方式顺序不明确链式组合顺序可控可扩展性有限AOP 模式灵活拦截5.3 典型应用场景日志追踪在 onModelCall 记录每次模型调用的 Token 消耗权限检查在 onActing 拦截敏感工具调用上下文注入在 onSystemPrompt 动态注入业务上下文性能监控在 onReasoning 统计推理耗时六、Human-in-the-LoopHITL人在环中6.1 设计理念AgentScope 2.0 将 HITL 作为框架内生能力而非外挂脚手架可在执行中确认工具参数、审批敏感操作或把执行交给外部系统。Agent 在暂停点等待并精确恢复无需自己搭脚手架。6.2 中断-恢复机制Agent 推理中... ↓ 触发工具调用敏感操作 ↓ 事件流发出 PermissionRequestEvent ↓ Agent 暂停等待人工审批 ↓ 人工确认 / 拒绝 / 修改参数 ↓ Agent 从暂停点精确恢复上下文不丢失6.3 权限三态模型工具调用请求 ↓ ┌─────────────────────────────┐ │ 权限决策引擎 │ │ 静态规则 工具类型 输入分析│ └─────────────────────────────┘ ↓ ↓ ↓ Allow Approve Deny 直接执行 人工审批 阻断七、AgentStateStore状态持久化7.1 无状态设计 外部状态存储AgentScope 2.0 的 Agent 在调用之间是无状态的。状态通过 AgentStateStore 外部化存储// 开发环境JSON 文件JsonFileAgentStateStore.builder().basePath(Paths.get(~/.agentscope/state)).build();// 生产环境RedisRedisAgentStateStore.builder().redisClient(redisClient).build();// 生产环境MySQLMysqlAgentStateStore.builder().dataSource(dataSource).build();7.2 状态存储后端对比后端适用场景特点内存单元测试最快进程重启丢失JSON 文件开发/单机零配置不支持并发集群MySQL生产集群强一致性支持事务Redis高并发生产高性能支持 TTL7.3 优雅上下线同一 (userId, sessionId) 在任意进程恢复完整对话支撑零停机滚动发布崩溃自动恢复水平扩缩容八、RuntimeContext多租户隔离的钥匙8.1 核心概念每次调用通过 RuntimeContext 传入身份上下文RuntimeContextctxRuntimeContext.builder().sessionId(session-001)// 会话标识.userId(alice)// 用户标识.orgId(org-001)// 组织标识可选.build();8.2 隔离维度维度隔离范围说明sessionId会话级不同对话完全隔离userId用户级不同用户数据不互通orgId组织级多租户企业场景agentIdAgent级同一用户可拥有多个 Agent8.3 并发安全场景行为同一 (userId, sessionId) 并发请求自动串行化不同 session 的请求完全并行九、HarnessAgent生产就绪的推荐入口9.1 在 ReActAgent 之上叠加的能力HarnessAgentagentHarnessAgent.builder().name(note-taker).sysPrompt(你是一个帮助用户做笔记的助手。).model(dashscope:qwen-plus)// 以下为 Harness 工程化能力 .workspace(Paths.get(.agentscope/workspace))// 工作区.compaction(CompactionConfig.builder()// 上下文压缩.triggerMessages(30).keepMessages(10).build()).build();9.2 Harness 叠加能力一览能力说明Workspace人格、知识、技能、日志全部以磁盘 Markdown/JSON 表达记忆压缩自动压缩 MEMORY.md 长期记忆 事实流水账Session 持久化AgentState 自动写回/加载子 AgentMarkdown 声明规格运行时按需 spawn沙箱隔离本地/Docker/远端 AgentRun 三种模式计划模式只读规划态编排长任务技能沉淀成功模式自动沉淀为 Markdown 技能十、消息模型统一 ContentBlock10.1 设计原则AgentScope 2.0 重构了消息模块通过统一的 ContentBlock 承载多种内容类型// 文本、文件、图片、音视频、模型思考、工具结果// 统一收敛到一个 ContentBlockMsgmsgMsg.builder().role(MsgRole.USER).content(TextBlock.builder().text(你好).build()).build();10.2 按 Role 严格校验消息按 roleUSER / ASSISTANT / SYSTEM / TOOL严格校验非法消息在构造期就被拦下避免运行时错误。十一、完整实战示例11.1 带工具的 ReActAgentpublicclassAgentWithToolsDemo{publicstaticvoidmain(String[]args){// 1. 定义工具ToolkittoolkitToolkit.builder().register(newWeatherTools()).register(newSearchTools()).build();// 2. 构建 AgentReActAgentagentReActAgent.builder().name(weather-assistant).sysPrompt(你是一个天气查询助手可以查询天气和搜索信息。).model(dashscope:qwen-plus).maxIterations(5).toolkit(toolkit).build();// 3. 调用Msgresponseagent.call(newUserMessage(北京明天天气怎么样适合出门吗)).block();System.out.println(response.getTextContent());}}11.2 生产级 HarnessAgent Spring WebFlux 流式输出RestControllerpublicclassAgentController{privatefinalHarnessAgentagent;publicAgentController(){this.agentHarnessAgent.builder().name(customer-service).sysPrompt(你是客服助手。).model(dashscope:qwen-plus).workspace(Paths.get(/data/agentscope/workspace)).compaction(CompactionConfig.builder().triggerMessages(50).keepMessages(15).build()).build();}GetMapping(value/chat,producesMediaType.TEXT_EVENT_STREAM_VALUE)publicFluxServerSentEventStringchat(RequestParamStringmessage,RequestParamStringsessionId,RequestParamStringuserId){RuntimeContextctxRuntimeContext.builder().sessionId(sessionId).userId(userId).build();returnagent.streamEvents(newUserMessage(message),ctx).filter(event-eventinstanceofTextDeltaEvent).map(event-ServerSentEvent.builder(((TextDeltaEvent)event).getDelta()).build());}}十二、从 1.x 迁移到 2.0 的关键变化变化点1.x2.0扩展机制Hook扁平回调Middleware五阶段结构化消息模型多种 Msg 子类统一 ContentBlock长期记忆LongTermMemory 接口MEMORY.md Compaction Tool状态持久化手动管理AgentStateStore 自动写回HITL需自行搭建框架内生暂停-恢复原生支持Spring 集成agentscope-spring-boot-starter手动注册 Bean更灵活模型容错手动重试FallbackModel 主备自动切换兼容性说明ReActAgent.longTermMemory() 在 RC2 中标记为 Deprecated(forRemovaltrue)1.x 代码仍可编译但建议迁移。十三、设计哲学总结AgentScope Java 2.0 的 Agent 构建块体现了三个核心设计哲学13.1 透明可控不对模型加过多约束让 Agent 自主推理和工具调用。框架提供的是基础设施而非行为约束。13.2 渐进式复杂度从 ReActAgent10 行代码跑通到 HarnessAgent生产级全家桶能力按需叠加不强制一次性引入所有复杂度。13.3 生产优先无状态设计 外部状态存储 RuntimeContext 隔离从第一天就为多租户、分布式、高并发而设计。十四、结语AgentScope Java 2.0 的 Agent 构建块不只是一个调用大模型的封装类而是一个完整的推理引擎 工程化运行时。它将 ReAct 推理循环、工具调用、中间件扩展、人在环中、状态持久化、多租户隔离等能力以 Java 开发者最熟悉的 Builder 接口 注解方式呈现真正实现了从跑通一个 Demo到稳定运行一个生产系统的无缝跨越。
