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

云烟成雨TD2026-06-13 11:47

文章目录

  • [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 的每一次工具调用，给出三种决策之一：

复制代码 
静态规则 + 工具类型 + 输入分析 → 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) 为索引。

复制代码 
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 再执行、可复用能力如何沉淀。

三条核心原理：

  1. 能力是叠加的，不是改写循环 。工作区注入、压缩、子 Agent、沙箱、Plan Mode ------ 每个能力都钩在 ReAct 循环的关键时机
  2. 能力之间互不依赖，只通过共享对象通信 ：RuntimeContext（这次 call 是谁）、工作区（谁读写哪些文件）、AgentStateStore（跨调用怎么恢复）
  3. 内置 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 在动手前先**"把意图想清楚 + 写下来**"再执行。开启后进入只读阶段：

复制代码 
设计 → 写计划(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(...) 自动完成接线。

相关推荐
Xiaofeng36932 小时前
三大旗舰模型横评：Claude 4.6、ChatGPT 5.5、Gemini 2.0 Pro 谁更强
人工智能
benben0442 小时前
Gym从入门到精通
人工智能
Zaimmm2 小时前
ChatGPT医疗智能体能做文献检索和指南比对吗？
人工智能·chatgpt
qq_382949222 小时前
企业级机器学习落地实战（含源码与课件）
人工智能·机器学习
愛～杦辷个訾2 小时前
Java Springboot使用阿里云oss对图片进行等质量压缩，转换成webp格式的压缩图。
java·spring boot·阿里云·oss
小鹿研究点东西2 小时前
AI直播复盘实操：如何自动录制并拆解直播话术
人工智能·自动化·音视频
意图共鸣2 小时前
“超级个体”的技术前提是什么？意图共鸣科技《AI记忆链商业化白皮书3.0》提到记忆主权与专属AI终端
人工智能·科技
蚂蚁数据AntData2 小时前
从ChatBI到业务记忆：重新定义数据智能的生产力边界
大数据·网络·数据库·人工智能·算法
热门推荐
01HTTP 与 HTTPS 的区别：从原理到实战详解02《置身钉内》原文-可播放阅读03【AI】2026 年具身智能模型和世界模型总结042026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？05Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析06AI科技热点日报 | 2026年6月1日072026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？08GitHub 镜像站点09AI一周事件 · 2026-06-03 至 2026-06-09102026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf