不只是调用大模型：一文看懂 AgentScope 2.0

不只是调用大模型：一文看懂 AgentScope 2.0

会聊天，只是大模型应用的起点；能安全、稳定地完成一项任务，才是智能体真正的价值。

过去两年，不少团队都做过类似的 AI Demo：接入一个大模型，写一段 Prompt，再注册几个工具，一个"智能助手"很快就能跑起来。

但 Demo 一旦进入真实业务，问题马上就来了：

• 模型调用到一半超时，任务还能不能继续？
• Agent 要删除文件、执行命令、调用退款接口，谁来控制权限？
• 对话越来越长，Token 成本和上下文窗口怎么控制？
• 同时服务多个用户时，状态如何隔离？
• 应用发布新版本或 Pod 重启后，进行到一半的任务会不会丢？
• 如何让前端看到 Agent 正在思考、调用工具或等待审批，而不是只有一个转圈动画？

这些问题已经超出了"封装一次大模型 API"的范畴。AgentScope 2.0 要解决的，正是智能体从 Demo 走向真实系统时的工程问题。

官方将这次升级概括为"从透明开发到系统工程"：AgentScope 1.0 更关注让开发者看清 Agent 如何接收消息、调用工具和组织协作，2.0 则进一步面向长期运行、安全控制、状态恢复和生产部署。AgentScope 2.0 发布文章

一、先说清楚：Agent 和普通聊天机器人有什么区别？

普通聊天机器人通常遵循一条很短的链路：

用户提问 → 调用大模型 → 返回文本

Agent 的链路更像一个能够自主推进工作的数字员工：

flowchart LR U["理解用户目标"] --> P["规划下一步"] P --> M["调用大模型推理"] M --> D{"是否需要工具"} D -->|是| T["调用搜索、数据库、业务接口或代码工具"] T --> O["观察执行结果"] O --> P D -->|否| R["生成最终结果"]

它不只回答问题，还会根据目标决定下一步行动。例如，一个"售后 Agent"可能需要：

1. 查询订单；
2. 判断是否符合退款条件；
3. 请求用户确认；
4. 调用退款接口；
5. 发送处理结果；
6. 记录完整操作日志。

这意味着 Agent 应用必须同时处理模型、工具、状态、权限、流程和人机协作。AgentScope 2.0 本质上就是为这些问题提供一套工程底座。

二、生产级智能体开发框架要具备哪些条件？

判断一个智能体框架是否达到生产级，不能只看它是否支持 ReAct、Tool Calling 或接入了多少模型。真正的生产系统至少要同时面对可靠性、安全性、状态管理、隔离、可观测性和持续治理。

下面给出一份更接近企业技术选型的评估矩阵：

生产能力	为什么必要	AgentScope 2.0 的支持	结论
模型容错	一次超时可能中断整条任务链	支持多模型 Provider、超时配置及 onModelCall 扩展；统一重试、备用模型与路由策略仍需结合 Middleware、模型客户端或企业模型网关实现	部分满足
状态持久化与恢复	Pod 重启、滚动发布后任务不能丢	AgentStateStore、Session 恢复、Redis/MySQL/OSS 集成	满足框架层要求
多用户与多租户隔离	不同用户的上下文、文件和工具状态不能串数据	AgentState 原生按 (userId, sessionId) 隔离，沙箱支持 SESSION / USER / AGENT / GLOBAL Scope；租户信息可通过 RuntimeContext 扩展	基本满足，租户鉴权和业务数据隔离需自建
权限与人工审批	Agent 不能无条件执行退款、删除、Shell 等操作	ALLOW / ASK / DENY、Permission Mode、内置动态检查、HITL	满足框架层要求
长任务上下文治理	历史消息和工具结果会快速撑爆上下文	支持结构化压缩、工具结果卸载、长期记忆和计划状态；相关策略默认关闭，需要显式配置	满足，但必须正确配置
不可信代码隔离	代码和命令不能直接污染宿主机或其他用户环境	Docker、Kubernetes、E2B、AgentRun 等沙箱及快照机制	满足，但必须正确配置
执行过程可观测	需要知道模型、工具和审批卡在哪一步	类型化事件流与 Middleware 扩展点	基本满足，监控平台需接入
工程扩展能力	日志、Tracing、限流、鉴权不能侵入 Agent 核心	Tool、MCP、Skill、Middleware、Workspace 抽象	满足
分布式部署	多副本必须共享状态、工作区和沙箱快照	DistributedStore 及远程文件系统	满足框架层要求
效果评测与 LLMOps	Prompt、Skill、模型升级不能靠人工感觉验收	可通过事件和 Middleware 扩展，但不是开箱即用的完整评测平台	部分满足
业务级安全与合规	数据权限、审计、脱敏、事务必须符合企业制度	框架提供权限底座，业务规则仍需企业实现	需要业务侧补齐

结论：它满足吗？

结论不是简单的"满足"或"不满足"，而是要分层来看：

• 作为智能体运行框架，基本满足生产级要求。 AgentScope 2.0 已经覆盖会话状态恢复、用户与会话隔离、权限三态、Human-in-the-Loop、上下文治理、沙箱、事件流和分布式存储等关键能力。它解决了大量原本需要团队自行搭建的智能体基础设施问题。
• 作为一套完整的企业 AI 平台，还不能开箱即用。 用户认证、组织权限、领域规则、数据脱敏、审计报表、模型评测、成本治理、告警、灾备和业务审批仍然需要接入企业现有平台或自行建设。
• 是否真正达到生产级，最终取决于配置和工程实践。 使用本地 JSON 状态、宿主机文件系统和无限制 Tool 的 AgentScope 应用，依然只是 Demo；换成分布式状态、强隔离沙箱、明确权限、可恢复的会话与工作区，以及完整监控之后，才具备生产系统的基础。

换句话说，AgentScope 2.0 提供了生产级智能体的"地基和承重结构"，但业务团队仍要完成水电、消防、门禁和验收。

正反对照一：状态是不是"真的可恢复"？

反面做法：

聊天记录放在单个 JVM 内存
→ Pod 发布或崩溃
→ 对话、计划、工具状态全部丢失
→ 用户只能重新开始任务

生产做法：

RuntimeContext 标识 userId + sessionId
→ AgentStateStore 保存上下文、摘要、权限和计划状态
→ Redis/MySQL 支撑多副本共享
→ 后续请求可由任意副本加载最近一次持久化状态并继续执行

AgentScope 2.0 官方生产指南明确指出，AgentState 是对话上下文、压缩摘要、权限规则、Plan Mode 状态和 Tool State 跨进程恢复的通路；多副本环境可选择 Redis，强调审计和关系查询的场景可使用 MySQL。AgentScope Java 2.0 上生产指南

需要注意，AgentState 主要在一次 call() 结束或应用优雅停机时整体持久化，并不是每产生一个流式事件就保存一次检查点。因此，这里的"恢复"是从最近一次已持久化状态继续，而不是承诺进程在单次调用中途崩溃后能够从最后一个事件精确续跑。

正反对照二：权限是不是只写在 Prompt 里？

反面做法：

System Prompt：请不要执行危险操作
→ 模型决定调用 deleteFile 或 refund
→ 工具无条件执行
→ Prompt 注入或模型误判直接变成真实事故

生产做法：

模型发起工具调用
→ Permission System 拦截
→ Rules + Mode + Built-in Checks 综合判断
→ ALLOW 自动执行 / ASK 等待审批 / DENY 拒绝

AgentScope 2.0 的 Permission System 会拦截每一次工具调用，显式返回 ALLOW、ASK 或 DENY；工具自身的动态安全检查不可被普通 Mode 或 Rule 绕过。AgentScope Java 2.0 权限系统

正反对照三：长任务是不是无限堆聊天记录？

反面做法：

每轮都把全部历史、日志和接口结果放入 Prompt
→ Token 成本持续上涨
→ 关键信息被噪声淹没
→ 最终上下文溢出，任务中断

生产做法：

近期消息保留原文
旧消息结构化压缩
超大工具结果落盘并保留引用
长期事实进入 Memory
任务目标、状态和下一步持续保留

AgentScope 2.0 的上下文治理已经不只是聊天摘要，而是面向长期任务保存目标、状态、关键发现和下一步，同时控制工具结果及文件内容对上下文窗口的占用。AgentScope 2.0 发布文章

在 AgentScope Java 2.0 中，这些策略并非全部默认开启：对话摘要需要配置 .compaction(...)，大工具结果卸载需要配置 .toolResultEviction(...)。只有显式启用并结合实际模型上下文窗口调整阈值，才能获得相应的治理效果。AgentScope Java 2.0 上下文压缩

三、AgentScope 2.0 能干什么？

1. 构建能调用工具的业务智能体

大模型擅长理解和推理，但它不知道企业数据库中的实时订单，也不能凭空完成退款、发邮件或修改文件。AgentScope 的 Tool 机制可以把 Java 方法、业务服务、MCP 服务和外部 API 暴露给 Agent。

模型负责判断"应该调用哪个工具、传什么参数"，工具负责完成确定性操作。于是，我们可以构建：

• 能查知识库、整理资料的企业知识助手；
• 能查询订单、创建工单的客服 Agent；
• 能分析日志、调用运维平台的故障排查 Agent；
• 能读取代码、运行测试、修改文件的研发 Agent；
• 能拆解任务并调度其他 Agent 的多智能体系统。

这里最重要的设计原则是：让模型负责决策，让工具负责执行，让权限系统负责守住边界。

2. 处理长时间、多步骤任务

裸的 ReAct 循环可以完成一次"思考---行动---观察"，但真实任务可能持续几十分钟甚至数小时。AgentScope Java 2.0 推荐使用 HarnessAgent，它将 Workspace、长期记忆、会话持久化、上下文压缩、Skill、子 Agent 和沙箱等能力组合在一个工程化入口中。AgentScope Java 2.0 概览

借助这些能力，Agent 可以：

• 把长期任务拆成计划并持续推进；
• 将稳定的做事方法沉淀为 Skill；
• 把专业子任务委派给子 Agent；
• 在对话过长时自动压缩上下文；
• 把关键事实保存为长期记忆；
• 在进程重启后恢复会话和任务状态。

这让 Agent 从"一次性回答器"变成了可以持续工作的任务执行系统。

3. 支持多用户和多租户运行

企业应用不可能只服务一个人。AgentScope 的 AgentState 原生以 (userId, sessionId) 为索引，同一个 Agent 实例可以并发服务多个用户，并保证不同用户与会话的状态相互隔离。沙箱执行环境还可以按 SESSION、USER、AGENT 或 GLOBAL 设置共享范围。租户、组织等业务信息可以通过 RuntimeContext 扩展字段传递，但租户成员关系、数据行权限和业务鉴权仍需应用层实现。上下文与 AgentState、Sandbox

开发环境可以使用本地 JSON 保存状态；多副本生产环境则可以使用 Redis 或 MySQL。官方生产指南指出，AgentStateStore 承载对话上下文、压缩摘要、权限规则、计划状态和工具状态，是跨进程恢复 Agent 状态的关键通路。AgentScope Java 2.0 上生产指南

4. 让前端实时展示 Agent 的执行过程

传统聊天接口往往只返回一段最终文本，但 Agent 的执行过程包含更多状态：模型开始推理、文本增量、工具调用、工具结果、用户确认和外部执行结果。

AgentScope 2.0 将这些过程统一为类型化事件流。前端可以通过 SSE 或其他流式协议实时展示：

正在理解问题......
正在调用订单查询工具......
已找到订单，等待用户确认退款......
退款接口执行成功......

这不只是体验优化。执行过程可见之后，系统才更容易调试、观测和审计。

5. 在隔离环境中执行代码和命令

研发 Agent、数据分析 Agent 经常需要运行 Python、Shell、编译命令或安装依赖。直接在宿主机执行这些操作风险很高。

AgentScope 2.0 的 Workspace 和 Sandbox 把"Agent 要做什么"与"在哪里执行"分开。同一个 Agent 可以切换到本地进程、Docker、Kubernetes、E2B 或 AgentRun 等不同执行环境。对于不可信代码、多用户硬隔离以及需要保留完整工作目录的场景，官方建议使用沙箱并配置 Snapshot，让任务切换节点后仍能恢复工作区。AgentScope Java 2.0 上生产指南

四、AgentScope 2.0 的七个核心亮点

亮点一：Harness------给 Agent 配上一套"操作系统"

如果说 ReActAgent 是推理引擎，那么 HarnessAgent 更像是一套面向复杂任务的操作系统。

它把下面这些能力整合起来：

• Workspace：统一管理人格、知识、技能、记忆和任务文件；
• Memory：区分当前上下文、事实流水和长期记忆；
• Compaction：自动压缩历史消息，控制上下文规模；
• Skill：将流程经验沉淀为可复用、可版本化的能力；
• Subagent：按需委派专业子任务；
• Plan Mode：先规划、后执行，使意图与动作分离；
• Sandbox：在隔离环境中运行文件和命令工具。

它解决的不是"如何再封装一个模型"，而是"如何让 Agent 长时间工作后依然可维护"。

亮点二：消息和事件不再只是字符串

在普通聊天系统里，一条消息可能只是 String。但 Agent 消息里可能同时存在文本、图片、文件、音频、模型思考、工具请求和工具结果。

AgentScope 2.0 使用统一的 ContentBlock 表达这些内容，并通过事件流暴露执行过程。模型调用、文本增量、工具执行和工具结果都可以被独立订阅。AgentScope 2.0 发布文章

这为多模态交互、Human-in-the-Loop、实时 UI 和执行过程审计打下了基础。

亮点三：权限系统让 Agent 的自主执行有边界

Agent 越强，风险越高。一个可以读文件、执行 Shell 和调用业务接口的 Agent，不能拥有无限权限。

AgentScope 2.0 会拦截每一次工具调用，并做出三态决策：

决策	含义	示例
ALLOW	自动放行	查询订单、读取公开资料
ASK	暂停并请求用户确认	退款、发送邮件、覆盖文件
DENY	直接拒绝	删除核心数据、执行高危命令

权限结果由显式 Rules、全局 Mode 和工具内置的运行时检查共同决定。EXPLORE 可用于只读探索，DONT_ASK 适合无人值守任务，将所有需要询问的操作自动降级为拒绝。AgentScope Java 2.0 权限系统

这套设计的意义在于：安全不再依赖 Prompt 中的一句"请不要做危险操作"，而是进入可执行、可审计的系统规则。

亮点四：上下文管理从"聊天记录"升级为"任务状态"

长任务最大的敌人之一是上下文膨胀。几十轮对话、海量日志和工具结果全部塞进 Prompt，不仅成本高，还会稀释真正重要的信息。

AgentScope 2.0 的上下文压缩会结构化保留：

• 任务目标；
• 当前状态；
• 关键发现；
• 下一步计划；
• 需要长期保留的事实。

超大的工具结果可以截断或落盘，文件读取可以使用缓存。上下文管理因此不只是"总结旧消息"，而是维持长期任务连续性的系统策略。AgentScope 2.0 发布文章

亮点五：Middleware 让横切能力不再侵入业务代码

日志、链路追踪、权限校验、输入改写、模型降级和成本统计，都是典型的横切能力。如果全部写入 Agent 或 Tool，代码很快会变得混乱。

AgentScope Java 2.0 的 Middleware 可以在五个位置介入执行链路：

• onAgent：包裹完整回复流程；
• onReasoning：包裹一次推理步骤；
• onActing：包裹一次工具执行；
• onModelCall：包裹底层模型 API 调用；
• onSystemPrompt：在系统提示词组装时注入或转换内容。

开发者无需修改 Agent 或模型代码，就能插入日志、Tracing、访问控制和输入改写逻辑。AgentScope Java 2.0 Middleware

对于 Java 开发者，可以把它理解成 Agent 生命周期中的 Filter、Interceptor 和 AOP。

亮点六：Workspace 让执行环境可以替换

Agent 的人格、技能和任务逻辑，不应该与某台机器的文件路径或某一种沙箱实现绑死。

Workspace 使用普通 Markdown、JSON 和目录结构统一组织人格、知识、Skill、子 Agent 与工具配置；文件访问再通过本地、远程或沙箱文件系统进行路由。这样可以减少 Agent 定义对具体机器路径和存储后端的依赖，使同一套智能体逻辑更容易在本地、容器和远程执行环境之间迁移。AgentScope Java 2.0 Workspace

亮点七：从一开始就考虑生产部署

AgentScope 2.0 明确区分了本地 Demo 和分布式生产环境：

• 本地 JSON 状态需要替换为 Redis 或 MySQL；
• 本地文件系统需要替换为远程或沙箱文件系统；
• 多用户数据需要设置隔离范围；
• 沙箱需要 Snapshot 和跨节点执行保护；
• Skill 应集中治理，生产环境不应自动晋升未经审核的技能；
• 不可信代码必须进入隔离环境执行。

官方提供 DistributedStore 统一配置状态、工作区和沙箱相关的分布式组件，降低从单机迁移到多副本部署的配置复杂度。AgentScope Java 2.0 上生产指南

五、Java 开发者如何快速上手？

AgentScope Java 2.0 需要 JDK 17 及以上版本，推荐 Maven 3.9+。官方建议复杂应用从 HarnessAgent 开始；如果只需要一个轻量 ReAct 循环，则可以仅使用 agentscope-core。AgentScope Java 2.0 快速开始

下面是一个最小化示例：

HarnessAgent agent = HarnessAgent.builder()
        .name("note-taker")
        .sysPrompt("你是一个帮助用户整理笔记的助手。")
        .model("dashscope:qwen-plus")
        .workspace(Paths.get(".agentscope/workspace"))
        .compaction(CompactionConfig.builder()
                .triggerMessages(30)
                .keepMessages(10)
                .build())
        .build();

RuntimeContext context = RuntimeContext.builder()
        .userId("user-001")
        .sessionId("session-001")
        .build();

agent.call(new UserMessage("帮我整理今天的会议纪要"), context)
        .block();

这个简单配置背后已经包含了几个重要能力：模型注册、工作区、会话上下文和历史消息压缩。继续注册 Tool、Skill、Middleware 和分布式状态存储，就可以逐步演进为完整的业务 Agent。

六、场景验证：用了 AgentScope，就等于生产级吗？

AgentScope 2.0 更适合"需要推理并执行"的场景，而不是所有 AI 功能。

下面通过三个高风险、高价值场景，看清"能运行"和"能上生产"的差别。

场景一：客服退款 Agent

用户说："这个订单买错了，帮我退款。"Agent 需要查询订单、判断退款政策、计算退款金额、获得确认并调用支付接口。

Demo 方案：

用户输入
→ 大模型判断是否退款
→ 直接调用 refund(orderId)
→ 返回"退款成功"

问题很明显：模型可能选错订单，Prompt 注入可能诱导越权退款，重复请求可能导致重复扣账，接口执行到一半失败后也无法判断任务状态。

生产方案：

认证用户并注入租户、用户上下文
→ 只读工具查询订单和退款规则
→ 领域服务确定是否可退及退款金额
→ Permission System 返回 ASK
→ 用户确认订单、金额和退款方式
→ 幂等退款工具执行事务
→ 记录工具参数、审批人、执行结果和 Trace ID
→ 通过事件流返回进度

AgentScope 能提供上下文隔离、工具调用、ASK 审批、事件流、状态恢复和 Middleware；但订单归属校验、退款规则、幂等键、支付事务和财务审计必须由业务系统提供。

判断：适合，但不能让模型直接掌握资金操作。 Agent 负责理解和编排，最终决策与执行必须落到确定性的领域规则和权限体系。

场景二：研发与运维 Agent

用户说："分析生产环境错误日志，修复代码并重新部署。"这类任务包含读日志、改代码、运行测试、构建镜像和执行部署。

Demo 方案：

Agent 直接在应用宿主机执行 Shell
→ 读取任意路径
→ 修改主分支代码
→ 执行 kubectl apply

一旦模型误判或遭遇恶意输入，可能泄露密钥、删除文件、污染宿主机，甚至直接影响生产集群。

生产方案：

EXPLORE 模式只读分析日志和代码
→ 形成修复计划
→ 为当前 Session 创建独立沙箱
→ 在沙箱分支修改代码并运行测试
→ 高风险命令触发 ASK
→ 提交 Pull Request
→ CI、安全扫描和人工审核通过后再部署
→ Snapshot 保存工作区，节点切换后继续

AgentScope 的 Permission Mode、Sandbox、Snapshot、Plan Mode、事件流和 Workspace 正好覆盖这一场景的核心基础设施。但代码仓库保护规则、CI/CD 准入、制品签名、Kubernetes RBAC 和生产发布审批仍属于企业 DevSecOps 体系。

判断：高度适合。 这也是权限、沙箱和任务恢复价值最容易体现的场景，但必须坚持"Agent 提交变更，流水线决定能否上线"。

场景三：医疗随访 Agent

用户说："根据患者出院记录生成随访计划，向患者推送提醒，发现高风险情况时通知医生。"

Demo 方案：

把完整病历直接发给大模型
→ 模型自由生成医疗建议
→ 自动向患者推送

这种方案存在隐私泄露、信息错配、医疗幻觉、责任边界不清和高风险结果无人审核等问题。

生产方案：

按医院、科室、医生和患者校验数据权限
→ 对进入模型的内容最小化并脱敏
→ RAG 检索审核过的指南和知识库
→ 结构化输出随访计划草案
→ 规则引擎检查时间、频率和禁忌项
→ 高风险内容进入医生审核
→ 审核通过后调用消息工具发送
→ 全链路记录知识版本、模型版本和审核结果

AgentScope 可以承载多租户上下文、工具编排、知识检索、结构化事件、权限审批和任务状态；但患者授权、病历访问控制、医疗知识质量、临床规则、个人信息保护和医生责任流程必须由医疗业务平台实现。

判断：适合做辅助和流程编排，不适合无监督替代医生决策。

一张表看懂场景边界

场景	AgentScope 适合承担	不应交给模型自由决定
客服退款	意图识别、流程编排、信息收集、审批等待、结果解释	订单归属、退款资格、金额计算、资金事务
研发运维	日志分析、代码修改、测试执行、PR 生成、进度汇报	绕过 CI 直接发布、读取任意密钥、无审批执行高危命令
医疗随访	信息整理、知识检索、计划草拟、提醒编排、风险上报	诊断、处方、无审核高风险建议、越权访问患者数据
企业知识助手	检索、摘要、引用、文档生成	绕过文档 ACL、把未验证生成内容当公司事实
多智能体系统	任务拆解、专业 Agent 委派、结果汇总	无边界递归委派、共享所有用户上下文、缺少最终责任人

如果需求只是摘要、分类、翻译或固定格式生成，直接调用大模型往往更简单。只有当任务需要多轮决策、工具调用、状态延续和安全治理时，Agent 框架的价值才会真正体现出来。

七、也要保持清醒：框架不能替你解决所有问题

AgentScope 提供的是智能体工程底座，不是完整业务系统。真正上生产时，团队仍然需要自己建设：

• 业务身份认证与租户权限；
• Tool 的参数校验、幂等和事务；
• Prompt 与 Skill 的版本管理；
• 模型效果评测和回归测试；
• Token、延迟和费用监控；
• 敏感数据脱敏与合规审计；
• 降级、限流、熔断和人工兜底；
• 高风险操作的审批流程。

尤其要避免三个误区：

1. 把 Prompt 当权限系统：提示词只能影响模型行为，不能替代强制执行规则。
2. 把聊天记录当长期记忆：长期记忆需要筛选、分层、持久化和生命周期治理。
3. 把 Demo 跑通当生产可用：多副本状态、沙箱快照、失败恢复和可观测性都需要单独验证。

八、总结

AgentScope 2.0 最值得关注的变化，不是新增了多少模型，也不是让 Agent 的回答更"聪明"，而是开始系统性回答一个更困难的问题：

如何让一个能够自主调用工具的智能体，在真实业务中长期、安全、可恢复地完成任务？

它给出的答案包括 Harness、统一消息与事件、三态权限、结构化上下文管理、Middleware、Workspace、分布式状态和沙箱执行。

对于 Java 团队来说，这套设计尤其容易与现有 Spring Boot 微服务、Redis、MySQL、Kubernetes、权限平台和可观测体系结合。我们可以先从一个能够调用工具的小型 Agent 开始，再逐步补齐状态、权限、记忆、事件和部署能力。

从这个角度看，AgentScope 2.0 不只是一个"智能体 SDK"，更像是 Java Agent 应用从实验走向工程化的一套运行底座。

参考资料

• AgentScope 2.0：从透明开发到系统工程
• AgentScope Java 2.0：什么是 AgentScope 2.0？
• AgentScope Java 2.0 快速开始
• AgentScope Java 2.0 上生产指南
• AgentScope Java 2.0 权限系统
• AgentScope Java 2.0 Middleware