目录1. 概述2. 核心组件2.1 Agent2.2 消息与事件2.3 中间件2.4 模型2.5 权限系统2.6 工具2.7 上下文与 AgentState3. Harness 工程3.1 上下文压缩3.2 工作区3.3 记忆3.4 文件系统3.5 沙箱3.6 子 Agent3.7 技能3.8 计划模式3.9 通道路由1. 概述AgentScope Java是一个面向JVM的开源Agent框架核心能力包括ReAct推理、Harness工程化基础设施、多智能体编排以及对MCP/A2A协议的原生支持。它覆盖了从本地原型到企业级分布式部署的完整链路。选择AgentScope的三大理由上手门槛低内置ReAct智能体、工具技能、人工干预、记忆、任务规划、实时语音、效果评估与模型微调能力五分钟即可搭建一个可用的智能体扩展性强生态完善兼容各类工具、记忆与可观测组件原生支持MCP、A2A协议借助MsgHub消息中心可灵活编排多智能体工作流生产就绪支持本地、Serverless云端、K8s集群等多种部署方式并内置OpenTelemetry可观测能力2. 核心组件2.1 AgentAgent默认实现为ReActAgent是AgentScope的核心抽象本质是一个推理-行动循环引擎。它将模型、工具、权限系统、人机交互、上下文管理、中间件、状态管理和事件系统整合到统一接口中。它的主要职责包括接收输入消息或事件调用工具完成任务管理上下文在关键生命周期阶段提供中间件钩子支持自定义逻辑自动管理并发与串行工具执行2.2 消息与事件Message与Event是AgentScope中两种基础数据结构定位各有侧重类型定位说明Message智能体间通信与持久化每个Msg代表一个完整对话轮次存储在上下文中并在智能体间传递Event前端交互与流式传输携带增量进度文本 token、工具调用片段、权限请求等驱动实时 UI 和 HITL 工作流单次call()调用产生的事件序列最终汇聚成恰好一条assistant Msg这意味着完整的消息状态始终可以从事件流中还原。2.3 中间件Agent Middleware允许在不修改agent或model代码的前提下向agent执行流程的关键位置注入自定义逻辑如日志、追踪、输入改写、访问控制。AgentScope Java在5 个位置设置Hook覆盖从外层reply流程到底层模型API调用的全链路位置类型说明onAgentOnion洋葱包裹一次完整的 reply 流程覆盖所有 ReAct 轮次、工具执行与最终输出onReasoningOnion洋葱包裹一轮 ReAct 的推理步骤输入组装 → 模型调用 → 流式解码onActingOnion洋葱包裹一次工具调用的执行onModelCallOnion洋葱包裹一次底层 ChatModel API 调用最贴近模型onSystemPromptTransformer变换在每次组装 system prompt 时触发多个 middleware 串行接力两种类型的关键区别Onion洋葱式middleware包裹下一层handler可在next.apply(input)前后插入逻辑、观察中间事件流Transformer变换式middleware之间串成流水线前一个的输出作为后一个的输入不存在内层概念2.4 模型模型层采用两层结构Credential承载apiKey、baseUrl等认证字段通过listModels()获取该提供商支持的模型列表ChatModel在Credential基础上实现的具体模型推理这种分层让界面只需鉴权一次就能展示该提供商支持的所有模型。2.5 权限系统Permission System拦截Agent的每一次工具调用给出三种决策之一静态规则 工具类型 输入分析 → ALLOW允许/ DENY拒绝/ ASK询问用户决策由三个组件共同决定组件说明Rules针对每个 tool 与命令的显式 allow/deny/ask 模式最高优先级。来源静态预配置 ASK 提示中用户接受后动态加入Mode全局静态策略决定所有不命中规则的调用的默认行为如EXPLORE只读、DONT_ASK静默拒绝Built-in Checks由 tool 自身在运行时基于真实输入做的动态分析不可绕过不受 mode 或 rules 覆盖2.6 工具Tool是Agent与外部世界交互的方式。AgentScope把Tool相关构件组织为三个概念概念说明Tool实现AgentTool接口继承ToolBase或标注Tool注解的对象。后者称为 reflective function toolToolkit容器负责注册 tool/MCP 客户端/skill向模型暴露 JSON Schema分发工具调用Tool Group一组带名称的 tool/MCP/skill 集合可作为整体激活或停用Agent 通过 meta tool 在运行时切换2.7 上下文与 AgentStateReActAgent以及HarnessAgent采用无状态引擎设计agent实例只持有不可变配置所有per-session可变数据放在AgentState以(userId, sessionId)为索引。HarnessAgent (单例不可变配置) │ ├─ (alice,s1) → AgentState ← 不同 session 并行 └─ (bob,s2) → AgentState ← 同 session 串行关键特性一个实例服务所有用户不同session完全并行同session自动FIFO串行call 入口自动加载退出自动保存调用方无需手动管理状态跨进程恢复分布式AgentStateStore如Redis下任意节点可恢复任意session支持故障转移和滚动发布AgentStateStore提供四种实现InMemory测试、JsonFile单机默认、Redis生产首选、MySQL审计场景。RuntimeContext承载per-call元数据userId/sessionId 自定义键值框架在call入口自动注入call-scoped的AgentState。3. Harness 工程HarnessAgent是ReActAgent的一层薄包装把长期运行Agent必备的工程能力打包进单一builder工作区驱动的人格、长期记忆、子Agent编排、沙箱隔离、技能装配、计划模式、Channel路由。裸的ReActAgent只解决一次请求 → 推理 → 工具 → 回复。Harness要回答的是另一组问题下一轮怎么接着上一轮、上下文如何保持有界、多用户如何隔离、危险操作如何先review再执行、可复用能力如何沉淀。三条核心原理能力是叠加的不是改写循环。工作区注入、压缩、子Agent、沙箱、Plan Mode—— 每个能力都钩在ReAct循环的关键时机能力之间互不依赖只通过共享对象通信RuntimeContext这次call是谁、工作区谁读写哪些文件、AgentStateStore跨调用怎么恢复内置 middleware 注册顺序固定自定义middleware跑在最前面3.1 上下文压缩LLM的token预算是有限的。HarnessAgent内置了四套正交的压缩策略策略解决的问题触发时机中间件对话摘要压缩上下文太深——消息条数太多每次模型推理前CompactionMiddleware大工具结果卸载上下文太宽——单条工具结果过大工具执行后ToolResultEvictionMiddleware上下文溢出兜底真的撞到模型 context_length_exceededcall() 抛错时HarnessAgent.recoverFromOverflow预压缩参数截断工具调用参数体量大但后期没人看摘要前的轻量预处理CompactionConfig.TruncateArgsConfig默认全部关闭按需.compaction(...)或.toolResultEviction(...)开启。3.2 工作区工作区是HarnessAgent智能体定义与进化的 source of truth。智能体是什么以及在运行中学到了什么全部以一个目录 Markdown/JSON文件组织。工作区文件结构定义内容文件人格、行为约定、系统指令AGENTS.md领域知识knowledge/KNOWLEDGE.md 参考文件技能skills/skill-name/SKILL.md子 Agent 声明subagents/agent-id.md工具白名单 MCP Servertools.json内容按生命周期分三类类型谁写谁读例子静态资产工程师框架每轮注入 system promptAGENTS.md、knowledge/、skills/、tools.json运行时文件框架/Agent框架下次 call 还原agents/id/sessions/、plans/长期记忆Agent 后台任务框架注入 Agent 工具查询MEMORY.md、memory/YYYY-MM-DD.md智能体如何进化全自动长期记忆MEMORY.mdmemory/从对话中提取的事实后台维护与压缩每轮注入自学习技能skills/Agent 从成功模式中起草新技能可选审批闸门后台 curator 自动老化归档计划文件plans/Plan Mode 中持久化跨调用保留工具结果落盘超大输出写到磁盘上下文只留 head/tail 预览会话日志agents/agentId/sessions/永不压缩的完整日志多租户隔离时工作区数据由单一的IsolationScope分桶IsolationScope谁共享典型场景SESSION每个 sessionId 完全隔离一次性沙箱USER默认同一 userId 的所有会话用户多会话共享记忆/技能AGENT该 Agent 的所有用户与会话共享知识库型 AgentGLOBAL整个 store 实例共用慎用3.3 记忆让Agent记住跨会话的事实同时避免对话上下文无限增长层级文件说明第一层·日流水账memory/YYYY-MM-DD.md每天追加原始且未去重第二层·长期记忆MEMORY.md周期性 LLM 合并去重的产物每轮注入 system prompt配套机制对话压缩、上下文溢出兜底、大工具结果卸载。3.4 文件系统把Agent对工作区的访问抽象成统一接口。所有文件工具read_file/write_file/edit_file/grep_files/glob_files/list_files和可选的executeshell都从这个抽象走。三种声明式模式模式配置Shell适用场景共享存储filesystem(new RemoteFilesystemSpec(store))❌多副本共享 MEMORY.md 到 KV不在宿主跑 shell沙箱filesystem(new DockerFilesystemSpec()...)或 K8s/Daytona/E2B/AgentRun✅沙箱内隔离执行、跨调用恢复、快照本机shell默认filesystem(new LocalFilesystemSpec()...)或不写✅宿主 sh -c单机/信任环境/测试3.5 沙箱把Agent的文件操作和命令执行收到隔离环境中宿主完全不参与。三个核心价值执行边界不可信输入、危险命令都关进沙箱宿主无感跨调用恢复沙箱状态pip install、npm install、临时文件可快照下次call继续多副本可用跨进程共享同一沙箱slot任意节点resume3.6 子 Agent让主Agent把可独立处理、上下文重、可并行的任务委派出去避免主线程膨胀。声明方式工作区workspace/subagents/id.md--- description: 代码审查专家。当用户需要 review PR、找代码问题、检查代码规范时使用。 --- 你是一个专注代码评审的子 agent。请按以下流程工作 1. 先 read_file / grep_files 收集上下文 2. 给出按文件 / 行号的具体建议 3. 末尾给一个 1-5 的总体评分主Agent调用agent_spawn agent_idreviewer taskreview 这次 PR 的所有改动来源适用配置内置 general-purpose通用兜底总是有不需要配工作区 spec 文件项目特有、可版本控制workspace/subagents/id.md编程式声明跑时才能确定builder.subagent(SubagentDeclaration.builder()...)3.7 技能一个skill就是一份写好的能力包目录里放SKILL.md用途和指令 参考文档/脚本/样例。两种来源技能市场Git仓库、Nacos、MySQL、classpath、自定义后端工作区workspace/skills/全局共享userId/skills/按用户隔离支持自学习闭环Agent起草skill→ 审核 → 后台周期性整理。3.8 计划模式让Agent在动手前先**把意图想清楚 写下来**再执行。开启后进入只读阶段设计 → 写计划(workspace/plans/) → HITL 确认 → 执行只能调用只读工具 4个白名单工具plan_enter/plan_write/plan_exit/todo_write其他工具调用一律被拒绝退出Plan Mode走HITL确认复用权限系统的ASK避免模型直接执行3.9 通道路由Gateway位于应用代码和Agent之间会话管理每个用户对话映射到稳定的session idPer-session 并发控制同一session消息公平排队Agent 路由多Agent场景下路由到正确AgentChannel把消息平台HTTP、WebSocket、Slack等适配成Gateway的路由模型。大多数场景下通过agent.channel(...)自动完成接线。