构建分布式、企业级智能体！
AgentScope Java 是面向 JVM 的开源 Agent 框架。提供 ReAct 推理、Harness 工程化基础设施、多智能体编排与 MCP/A2A 协议支持，覆盖从本地原型到企业级分布式部署全链路。
var agent = HarnessAgent.builder() .name("coder") .model("qwen-max") // ModelRegistry 解析，读取 DASHSCOPE_API_KEY .workspace(Paths.get(".agentscope/workspace")) // AGENTS.md · MEMORY.md · skills · subagents .filesystem(new DockerFilesystemSpec() // 沙箱执行：本地 · Docker · 远端 KV 一行切换 .isolationScope(IsolationScope.USER)) // 同一 user 跨 session 共享 .build(); agent.call(msg, RuntimeContext.builder() .sessionId("demo").userId("alice").build()).block();
io.agentscope:agentscope-harness:${agentscope.version}
长期稳定运行的工程底座。
裸的 ReActAgent 只解决"一次推理"，HarnessAgent 通过 Middleware 与 Toolkit 两个扩展通道，把工作区、记忆、沙箱、子 agent、技能与计划模式打包成一套面向长期稳定运行的工程基础设施——核心推理循环原样保留，只叠加不替换。
- 身份持续：工作区即 agent 的人格 + 长期记忆 + 领域知识，每轮自动注入
- 上下文可控：自动压缩、大工具结果落盘、ContextOverflow 兜底重试
- 状态可恢复：同 sessionId 跨进程恢复完整对话；沙箱状态可快照
- 能力可沉淀：四层 Skill 合成 + 自学习闸门；声明式子 agent 编排
让执行过程可展示、可干预。
消息通过统一 ContentBlock 承载文本、文件、图片、思考与工具结果；一次 call() 不再只返回最终文本，而是流式产生模型调用、文本增量、工具调用、工具结果、用户确认等类型化事件。HITL 与权限审批是框架内生能力。
- 类型化事件：
streamEvents()逐步发出，前端无需手动 diff - 多模态消息：
DataBlock同时兼容 base64 与 URL 两种数据源 - 权限三态决策：静态规则 + 工具类型 + 输入分析 → 允许 / 用户审批 / 拒绝
- 外部执行回环：工具可在外部环境完成后回写结果，任务继续推进
组成可靠智能体系统的核心组件
从模型容错到沙箱执行，AgentScope Java 2.0 把"让 Agent 稳下来"所需的每一块工程拼图都给齐。
模型容错
统一的 Credential + ChatModel 抽象，覆盖 Qwen / OpenAI / Anthropic / Gemini / DeepSeek / Ollama；可配置最大重试与备用模型，主模型不可用时自动切换。
了解模型 →上下文工程
结构化压缩保留目标 / 状态 / 关键发现 / 下一步；超大工具结果自动落盘、上下文只留占位符；文件读写强制"先读后改"，减少重复 IO。
了解记忆 →Middleware
onAgent / onReasoning / onActing / onModelCall 四个洋葱钩子 + onSystemPrompt 变换钩子。日志、追踪、权限、上下文注入、业务策略都能挂上去，框架核心保持稳定。
Workspace 抽象
把"agent 做什么"与"在哪里执行"分离。WorkspaceBase 统一身份、生命周期、资源发现与上下文卸载；本地磁盘、Docker、E2B 云沙箱一行切换；内置预热池适配 RL rollout。
了解 Workspace →多智能体
在 Markdown 里声明子 agent 规格，主 agent 在运行时按需 agent_spawn / agent_send，同步阻塞与后台委派两种模式。后台任务终态会通过 system-reminder 反向推送，不再要求轮询。
工具与 MCP
注解驱动的工具注册、按属性自动批处理串行或并发；统一接入任意 MCP 兼容服务器（文件系统、数据库、浏览器、代码解释器），workspace/tools.json 集中管理白名单。
准备好开始构建了吗？
跟着 quickstart 几分钟跑通一个 ReActAgent；需要工程化能力时换成 HarnessAgent，业务代码无须改动——同一套推理核心，按需叠加能力。
常见问题
完整问答见 FAQ，或到 GitHub Discussions 提问。
需要哪个 Java 版本？
需要 JDK 17 及以上。框架用了 Records、Sealed Classes 等现代特性，并基于 Project Reactor 提供非阻塞响应式执行模型。若需极低冷启动延迟，可通过 Quarkus 进行 GraalVM 原生镜像编译。
支持哪些 LLM 提供商？
开箱支持：OpenAI（含兼容端点 vLLM、DeepSeek、Kimi、Moonshot）、Anthropic Claude、阿里云通义千问（DashScope）、Google Gemini、xAI Grok、本地 Ollama。每个都是统一 builder 后面一份独立的 ChatModel 实现，可在模型层配置重试与备用模型实现容错切换。
Harness 和裸的 ReActAgent 有什么区别？
ReActAgent 是"推理 → 工具 → 回复"的核心循环；HarnessAgent 在此之上通过 Middleware 与 Toolkit 注入工作区、记忆、压缩、子 agent、沙箱、Plan Mode 与技能等工程能力，二者共享同一套推理核心。你可以从 ReActAgent 起步，需要长期稳定运行时无缝迁移到 HarnessAgent，业务逻辑不动。
2.0 兼容 1.0 吗？
AgentScope Java 2.0 版本尽量保持了对 1.x 版本的兼容，确保大部分用户的平滑升级；但同时 2.0 也带来了 API 层面的不兼容变更（新增类型化事件、权限系统、Middleware 栈与 Workspace 抽象等），详情可参考 Changelog。
能搭配 Spring Boot 或 Quarkus 使用吗？
可以。核心模块是与框架无关的 Java 库，可作为依赖加入任何 JVM 应用——Spring Boot、Quarkus、Micronaut 或纯 Java 都行。Quarkus 还能配合 GraalVM 编译原生镜像，做到 100 ms 内冷启动。
如何在生产环境中水平扩展？
AgentScope Java 天然支持无状态水平扩展：会话状态由 Session 自动持久化（默认 WorkspaceSession），工作区可挂到远端 KV / 对象存储，沙箱模式下连可执行环境本身都能跨调用 resume。配合 Kubernetes 与 HPA，任意副本均可恢复同一用户的完整上下文。