Agent Scope Java 2.x 系列【1】核心架构

- [1. 概述](#1. 概述)
- [2. 核心组件](#2. 核心组件)
- - [2.1 Agent](#2.1 Agent)
  - [2.2 消息与事件](#2.2 消息与事件)
  - [2.3 中间件](#2.3 中间件)
  - [2.4 模型](#2.4 模型)
  - [2.5 权限系统](#2.5 权限系统)
  - [2.6 工具](#2.6 工具)
  - [2.7 上下文与 AgentState](#2.7 上下文与 AgentState)
- [3. Harness 工程](#3. Harness 工程)
- - [3.1 上下文压缩](#3.1 上下文压缩)
  - [3.2 工作区](#3.2 工作区)
  - [3.3 记忆](#3.3 记忆)
  - [3.4 文件系统](#3.4 文件系统)
  - [3.5 沙箱](#3.5 沙箱)
  - [3.6 子 Agent](#3.6 子 Agent)
  - [3.7 技能](#3.7 技能)
  - [3.8 计划模式](#3.8 计划模式)
  - [3.9 通道路由](#3.9 通道路由)

1. 概述

AgentScope Java 是一个面向 JVM 的开源 Agent 框架，核心能力包括 ReAct 推理、Harness 工程化基础设施、多智能体编排，以及对 MCP/A2A 协议的原生支持。它覆盖了从本地原型到企业级分布式部署的完整链路。

选择 AgentScope 的三大理由：

上手门槛低 ：内置 ReAct 智能体、工具技能、人工干预、记忆、任务规划、实时语音、效果评估与模型微调能力，五分钟即可搭建一个可用的智能体
扩展性强 ：生态完善，兼容各类工具、记忆与可观测组件；原生支持 MCP、A2A 协议；借助 MsgHub 消息中心可灵活编排多智能体工作流
生产就绪 ：支持本地、Serverless 云端、K8s 集群等多种部署方式，并内置 OpenTelemetry 可观测能力

2. 核心组件

2.1 Agent

Agent（默认实现为 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 调用的全链路：

位置	类型	说明
`onAgent`	Onion（洋葱）	包裹一次完整的 reply 流程，覆盖所有 ReAct 轮次、工具执行与最终输出
`onReasoning`	Onion（洋葱）	包裹一轮 ReAct 的推理步骤（输入组装 → 模型调用 → 流式解码）
`onActing`	Onion（洋葱）	包裹一次工具调用的执行
`onModelCall`	Onion（洋葱）	包裹一次底层 ChatModel API 调用，最贴近模型
`onSystemPrompt`	Transformer（变换）	在每次组装 system prompt 时触发，多个 middleware 串行接力

两种类型的关键区别：

Onion（洋葱式） ：middleware 包裹下一层 handler，可在 next.apply(input) 前后插入逻辑、观察中间事件流
Transformer（变换式） ：middleware 之间串成流水线，前一个的输出作为后一个的输入，不存在"内层"概念

2.4 模型

模型层采用两层结构：

Credential ：承载 apiKey、baseUrl 等认证字段，通过 listModels() 获取该提供商支持的模型列表
ChatModel ：在 Credential 基础上实现的具体模型推理

这种分层让界面只需鉴权一次，就能展示该提供商支持的所有模型。

2.5 权限系统

Permission System 拦截 Agent 的每一次工具调用，给出三种决策之一：

text 复制代码

静态规则 + 工具类型 + 输入分析 → 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 tool
Toolkit	容器，负责注册 tool/MCP 客户端/skill，向模型暴露 JSON Schema，分发工具调用
Tool Group	一组带名称的 tool/MCP/skill 集合，可作为整体激活或停用，Agent 通过 meta tool 在运行时切换

2.7 上下文与 AgentState

ReActAgent（以及 HarnessAgent）采用无状态引擎设计 ：agent 实例只持有不可变配置，所有 per-session 可变数据放在 AgentState，以 (userId, sessionId) 为索引。

text 复制代码

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_exceeded	call() 抛错时	`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 Server	`tools.json`

内容按生命周期分三类：

类型	谁写	谁读	例子
静态资产	工程师	框架每轮注入 system prompt	AGENTS.md、knowledge/、skills/、tools.json
运行时文件	框架/Agent	框架下次 call 还原	agents/`<id>`/sessions/、plans/
长期记忆	Agent + 后台任务	框架注入 + Agent 工具查询	MEMORY.md、memory/YYYY-MM-DD.md

智能体如何进化（全自动）：

长期记忆 （MEMORY.md + memory/）：从对话中提取的事实，后台维护与压缩，每轮注入
自学习技能 （skills/）：Agent 从成功模式中起草新技能，可选审批闸门，后台 curator 自动老化归档
计划文件 （plans/）：Plan Mode 中持久化，跨调用保留
工具结果落盘：超大输出写到磁盘，上下文只留 head/tail 预览
会话日志 （agents/<agentId>/sessions/）：永不压缩的完整日志

多租户隔离时工作区数据由单一的 IsolationScope 分桶：

IsolationScope	谁共享	典型场景
`SESSION`	每个 sessionId 完全隔离	一次性沙箱
`USER`（默认）	同一 userId 的所有会话	用户多会话共享记忆/技能
`AGENT`	该 Agent 的所有用户与会话	共享知识库型 Agent
`GLOBAL`	整个 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）和可选的 execute（shell）都从这个抽象走。

三种声明式模式：

模式	配置	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，任意节点 resume

3.6 子 Agent

让主 Agent 把"可独立处理、上下文重、可并行"的任务委派出去，避免主线程膨胀。

声明方式 ：工作区 workspace/subagents/<id>.md：

markdown 复制代码

---
description: 代码审查专家。当用户需要 review PR、找代码问题、检查代码规范时使用。
---

你是一个专注代码评审的子 agent。请按以下流程工作：
1. 先 read_file / grep_files 收集上下文
2. 给出按文件 / 行号的具体建议
3. 末尾给一个 1-5 的总体评分

主 Agent 调用：agent_spawn agent_id="reviewer" task="review 这次 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 在动手前先**"把意图想清楚 + 写下来**"再执行。开启后进入只读阶段：

text 复制代码

设计 → 写计划(workspace/plans/) → HITL 确认 → 执行

只能调用只读工具 + 4 个白名单工具：plan_enter / plan_write / plan_exit / todo_write
其他工具调用一律被拒绝
退出 Plan Mode 走 HITL 确认（复用权限系统的 ASK），避免模型直接执行

3.9 通道路由

Gateway 位于应用代码和 Agent 之间：

会话管理 ：每个用户对话映射到稳定的 session id
Per-session 并发控制 ：同一 session 消息公平排队
Agent 路由 ：多 Agent 场景下路由到正确 Agent

Channel 把消息平台（HTTP、WebSocket、Slack 等）适配成 Gateway 的路由模型。大多数场景下通过 agent.channel(...) 自动完成接线。