0%

AgentScopeJava 项目架构分析

Posted on In

1. 概览

本文是对开源项目 agentscope-java（v2.0版本）进行的项目架构分析，以便帮助对该项目进行结构化理解与记忆。

2. 顶层目录结构

1
2
3
4
5
6
7
8
9
agentscope-java/
├── pom.xml                          # 根 POM (agentscope-parent)
├── agentscope-core/                 # 核心框架（Agent 模型、消息、中间件、工具、状态等）
├── agentscope-harness/              # 增强运行时（HarnessAgent、工作区、沙箱、子Agent）
├── agentscope-extensions/           # 可选扩展集（19 个分组父模块，内含 ~50+ 子模块）
├── agentscope-examples/             # 示例项目（agents / integration / multiagent-patterns）
├── agentscope-dependencies-bom/     # 外部依赖 BOM（统一管理所有第三方库版本）
├── agentscope-distribution/         # 打包分发（agentscope-all shaded JAR + agentscope-bom）
└── docs/                            # 文档

3. 整体分层架构

1
2
3
4
5
6
7
8
9
10
11
agentscope-dependencies-bom      ← 统一管理所有第三方库版本
        │
agentscope-parent (root POM)     ← Java 17, Maven Central 发布
        │
        ├── agentscope-core              ← ★ 核心层，零内部依赖
        │     ├── agentscope-harness     ← 增强运行时（沙箱/工作区/子Agent/技能策划）
        │     └── agentscope-extensions  ← 所有可选扩展（分组管理）
        │           └── Spring Boot / Micronaut / Quarkus Starters
        │
        ├── agentscope-distribution      ← 打包分发（shaded JAR + BOM）
        └── agentscope-examples          ← 示例项目（agents / integration / multiagent-patterns）

关键设计原则：

  • core 是唯一的基础：所有模块最终依赖 agentscope-core，core 本身零内部依赖
  • 扩展模块分组管理：扩展按功能域分组（model / rag / mem / channel / sandbox / scheduler / nacos / skills / protocol），每个分组是一个父 POM
  • 扩展声明为 optional：大部分扩展使用 <optional>true</optional> + <scope>provided</scope>，消费者按需引入
  • 技术栈：Java 17 + Reactor (响应式) + Jackson + OkHttp + SLF4J

4. 模块职责速览

模块 定位 核心能力
agentscope-core 框架基石 Agent 模型 (Agent/AgentBase/ReActAgent)、消息系统 (Msg/ContentBlock)、中间件链 (MiddlewareBase)、工具体系 (@Tool/Toolkit)、MCP 协议、权限引擎、RAG 框架、技能系统、AgentState 状态管理、细粒度事件流、链路追踪、凭证管理、优雅停机
agentscope-harness 增强运行时 HarnessAgent（生产级 Agent 运行时）、工作区管理 (WorkspaceManager)、沙箱执行 (Docker)、子 Agent 编排 (SubagentDeclaration)、文件系统 (Local/Remote/Sandbox Overlay)、技能策划 (SkillCurator/Promoter/Gate)、内存压缩 (ConversationCompactor)、中间件栈（14 个内置中间件）、Plan Mode 管理
agentscope-extensions 可选扩展集 模型供应商 (5个)、RAG 后端 (5个)、记忆后端 (3个)、通道集成 (6个)、沙箱后端 (4个)、调度器 (2个)、状态存储 (5个)、技能仓库 (3个)、Nacos 集成 (3个)、协议 (A2A/AG-UI/Chat-Web)、Spring Boot Starters (10个)、Micronaut、Quarkus
agentscope-distribution 分发打包 agentscope (shaded uber-JAR) + agentscope-bom (版本 BOM)
agentscope-examples 示例项目 Agent 示例 (Builder/Paw/Coding/Data/Claw/BobaTea)、集成示例 (A2A/AG-UI/Micronaut/Quarkus)、多Agent模式 (Handoff/Pipeline/Routing/Skills/Subagent/Supervisor/Workflow)

5. 核心依赖关系图

1
2
3
4
5
6
7
          agentscope-core (零内部依赖)
          /        |        \
         /         |         \
harness        extensions     framework-starters
(增强运行时)    (19个分组模块)   (Spring/Micronaut/Quarkus)
    |
    └── agentscope-extensions-agent-protocol

6. 模块详细分析

6.1 agentscope-core — 核心层

内部依赖: 无

核心外部依赖:

依赖 用途
io.projectreactor:reactor-core 响应式流 (Flux/Mono)，用于流式 Agent 响应
com.fasterxml.jackson.core:jackson-databind JSON 序列化/反序列化
com.fasterxml.jackson.datatype:jackson-datatype-jsr310 Java 8 日期时间支持
com.github.victools:jsonschema-generator JSON Schema 生成（工具定义 / 结构化输出）
com.github.victools:jsonschema-module-jackson Jackson 注解的 Schema 生成
org.slf4j:slf4j-api 日志门面
com.squareup.okhttp3:okhttp + okhttp-jvm HTTP 客户端
io.modelcontextprotocol.sdk:mcp MCP 协议 SDK
com.networknt:json-schema-validator JSON Schema 校验（工具输入校验）
org.yaml:snakeyaml YAML 解析
io.github.bonede:tree-sitter + tree-sitter-bash AST 级 Bash 安全检查
io.opentelemetry:opentelemetry-api 链路追踪
org.xerial:sqlite-jdbc 本地工作区索引
org.apache.commons:commons-compress 压缩/解压（沙箱 tar 包）
redis.clients:jedis (optional) Redis 快照后端
com.aliyun.oss:aliyun-sdk-oss (optional) 阿里云 OSS 快照后端

包结构 (io.agentscope.core):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
agent/               Agent, AgentBase, ReActAgent, CallableAgent, StreamableAgent, ObservableAgent, RuntimeContext
  accumulator/       消息累积与推理上下文
  config/            ReactConfig, ModelConfig
  user/              UserAgent (HITL)
credential/          凭证管理
event/               细粒度事件系统 (34 种 AgentEvent 类型: AgentStart/End, TextBlock*, ThinkingBlock*, ToolCall*, ToolResult*, DataBlock*, 确认/中断等)
exception/           核心异常
formatter/           模型请求/响应格式化器 (AbstractBaseFormatter)
hook/                生命周期钩子 (已废弃，v2 由 Middleware 替代)
  recorder/          录制钩子
interruption/        中断机制 (InterruptControl, InterruptContext)
memory/              记忆系统 (Memory 接口已废弃; InMemoryMemory, LongTermMemory, AgentStateMemoryView)
message/             消息模型 (Msg, MsgRole, ContentBlock 体系, UserMessage/AssistantMessage/SystemMessage/ToolResultMessage)
middleware/          中间件系统 (MiddlewareBase, MiddlewareChain, AgentInput, ReasoningInput, ActingInput, ModelCallInput, TaskReminderMiddleware)
model/               LLM 模型抽象 (Model, ChatModelBase, ModelRegistry, ChatResponse, GenerateOptions, ToolSchema, ExecutionConfig)
  spi/               ModelProvider SPI (扩展点，供模型供应商模块实现)
  transport/         传输层 (OkHttp / JDK / WebSocket)
  tts/               文本转语音
permission/          权限引擎 (PermissionEngine, PermissionMode, PermissionRule, PermissionBehavior)
rag/                 RAG 框架 (Knowledge, Document, RAGMode, GenericRAGHook, KnowledgeRetrievalTools)
  model/
shutdown/            优雅停机 (GracefulShutdownManager, GracefulShutdownMiddleware)
skill/               技能系统 (AgentSkill, SkillRegistry, SkillBox, SkillHook, DynamicSkillMiddleware, SkillToolFactory)
  repository/        技能仓库接口 (AgentSkillRepository, FileSystemSkillRepository, ClasspathSkillRepository)
  util/              技能解析工具 (MarkdownSkillParser, SkillFileSystemHelper)
state/               Agent 状态管理 (AgentState, AgentStateStore, InMemoryAgentStateStore, JsonFileAgentStateStore, TaskContextState, ToolContextState, PlanModeContextState)
tool/                工具体系 (@Tool 注解, Toolkit, ToolRegistry, ToolGroupManager, ToolExecutor, ToolSchemaProvider, MetaToolFactory, ReflectiveFunctionTool, SubAgentTool, McpTool)
  builtin/           内置工具 (TodoTools)
  coding/            代码执行工具 (ShellCommandTool, CommandValidator, tree-sitter 安全校验)
  file/              文件操作工具 (ReadFileTool, WriteFileTool)
  mcp/               MCP 客户端封装 (McpSyncClientWrapper, McpAsyncClientWrapper, McpClientBuilder)
  subagent/          子 Agent 工具配置 (SubAgentConfig, SubAgentProvider)
tracing/             链路追踪 (Tracer, TracerRegistry, NoopTracer, OtelTracingMiddleware)
util/                通用工具 (JsonUtils, TypeUtils)
workspace/           (预留包，工作区概念在 harness 中实现)

顶层类 (io.agentscope.core):

  • ReActAgent — 主 Agent 实现，执行 ReAct 循环（Reasoning → Acting → Summary）
  • Version — 版本信息

v2 核心架构要点

Agent 接口层次:

1
2
3
4
5
6
CallableAgent (interface) — call(Msg) → Mono<Msg>
StreamableAgent (interface, @Deprecated) — stream(Msg) → Flux<Event>（粗粒度事件流）
ObservableAgent (interface) — observe(Msg) → Mono<Void>
Agent (interface) extends CallableAgent, StreamableAgent, ObservableAgent
  └── AgentBase (abstract) — 生命周期管理、钩子调度、广播机制
        └── ReActAgent — 完整 ReAct 循环，中间件链，细粒度事件流

ReActAgent 执行循环 (每次迭代: Reasoning → Acting → Summary):

  1. Reasoning: 通过 onReasoning 中间件链 → 调用模型（流式）→ 收集文本/思考/工具调用
  2. Acting: 通过 onActing 中间件链 → 执行工具（并行/串行）→ PermissionEngine 权限检查
  3. Summary: 构建 AssistantMessage（含工具结果），决定是否继续迭代

循环终止条件：模型停止 / 达 maxIters / 中断 / stopOnReject

中间件系统 (v2 替代旧 Hook 体系):

1
2
3
4
5
6
MiddlewareBase
  ├── onAgent(AgentInput, Chain) → Mono<Msg>
  ├── onReasoning(ReasoningInput, Chain) → Mono<Msg>
  ├── onActing(ActingInput, Chain) → Mono<Msg>
  ├── onModelCall(ModelCallInput, Chain) → Flux<ChatResponse>
  └── onSystemPrompt() → String

细粒度事件系统 (v2，34 种事件类型):

1
2
3
4
5
6
7
8
9
10
11
AgentStart / AgentEnd / AgentResult
ModelCallStart / ModelCallEnd
TextBlockStart / TextBlockDelta / TextBlockEnd
ThinkingBlockStart / ThinkingBlockDelta / ThinkingBlockEnd
ToolCallStart / ToolCallDelta / ToolCallEnd
ToolResultStart / ToolResultTextDelta / ToolResultDataDelta / ToolResultEnd
DataBlockStart / DataBlockDelta / DataBlockEnd
RequireUserConfirm / UserConfirmResult
RequireExternalExecution / ExternalExecutionResult
ExceedMaxIters / AllToolsDenied / RequestStop
CustomEvent / HintBlock / SubagentExposed

状态管理 (v2):

  • AgentState 是核心的运行时状态容器（per-session，per-user 隔离）
  • 上下文存储在 AgentState.getContext() (List<Msg>)，而非独立的 Memory 对象
  • AgentStateStore 负责持久化（InMemory / JsonFile）
  • 旧 Memory 接口标记为 @Deprecated

权限系统 (v2 新增):

  • PermissionEngine — 工具调用权限评估
  • PermissionMode: ALWAYS_ALLOW / EXPLORE / ACCEPT_EDITS / HITL_ONLY / CUSTOM
  • PermissionRule — 允许/拒绝模式匹配
  • HITL (Human-in-the-Loop) 交互确认

模型解析机制:

  • ModelRegistry.resolve("openai:gpt-4o") 三级解析：已注册实例 → 工厂缓存 → SPI ServiceLoader
  • 模型供应商模块通过 META-INF/services/io.agentscope.core.model.spi.ModelProvider 注册
  • 模型 ID 格式："provider:model-name"（如 openai:gpt-4o, dashscope:qwen-max）

6.2 agentscope-harness — 增强运行时

内部依赖: agentscope-core (compile)

核心外部依赖:

依赖 用途
org.xerial:sqlite-jdbc 本地工作区索引
org.apache.commons:commons-compress Tar 解压 (沙箱)
redis.clients:jedis (optional) Redis 快照后端
com.aliyun.oss:aliyun-sdk-oss (optional) 阿里云 OSS 快照后端

注意：K8s/Protobuf 等沙箱后端依赖已迁移至 agentscope-extensions-sandbox-* 模块。

包结构 (io.agentscope.harness.agent):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
HarnessAgent.java           # 生产级 Agent 入口，封装 ReActAgent
HarnessAgentBuilderSupport.java  # Builder 模式构建支持
IsolationScope.java         # 隔离作用域
DistributedStore.java       # 分布式存储

bus/                        # 多 Agent 事件总线
filesystem/                 # 文件系统抽象 (AbstractFilesystem, OverlayFilesystem, Local/Remote/Sandbox)
gateway/                    # HarnessGateway, SubagentGatewayBridge
  channel/                  # Channel 抽象, chatui channel
memory/                     # 内存管理 (MemoryConfig, MemoryConsolidator, MemoryFlushManager)
  compaction/               # 对话压缩 (ConversationCompactor, CompactionConfig, ToolResultEvictionConfig)
  session/                  # 会话管理
middleware/                 # 14 个内置中间件:
                            #   WorkspaceContextMiddleware, InboxMiddleware, SubagentsMiddleware
                            #   HarnessRuntimeMiddleware, HarnessSkillMiddleware, AsyncToolMiddleware
                            #   CompactionMiddleware, ToolResultEvictionMiddleware
                            #   MemoryFlushMiddleware, MemoryMaintenanceMiddleware
                            #   SandboxLifecycleMiddleware, AgentTraceMiddleware
                            #   AtPathExpansionMiddleware, DynamicSubagentsMiddleware
sandbox/                    # 沙箱上下文 (SandboxContext, SandboxExecutionGuard, SandboxManager, SessionSandboxStateStore)
  impl/docker/              # Docker 沙箱实现
  json/                     # 沙箱 JSON Schema
  layout/                   # 沙箱布局
  snapshot/                 # 快照处理
skill/                      # 工作区技能仓库 (WorkspaceSkillRepository)
  curator/                  # 技能策划 (SkillCurator, SkillPromoter, SkillPromotionGate, SkillAuditLog, SkillUsageStore)
  runtime/                  # ShellPathPolicy
subagent/                   # 子 Agent 声明 (SubagentDeclaration)
  task/                     # 任务仓库 (TaskRepository, WorkspaceTaskRepository)
tool/                       # 工具集成 (FilesystemTool, ShellExecuteTool, Memory*, PlanModeTools, ProposeSkillTool, SkillManageTool, SessionSearchTool)
tools/                      # 工具配置 (McpServerRegistrar, ToolFilter, ToolsConfig, ToolsConfigLoader)
workspace/                  # 工作区管理 (WorkspaceManager, WorkspaceIndex, WorkspacePathNormalizer)
  plan/                     # Plan Mode 管理 (PlanModeManager)

HarnessAgent 中间件栈（按执行序）:

  1. WorkspaceContextMiddleware — 加载 AGENTS.md / MEMORY.md / KNOWLEDGE.md
  2. InboxMiddleware — 待处理消息收件箱
  3. SubagentsMiddleware — 子 Agent 编排
  4. HarnessRuntimeMiddleware — 运行时连接
  5. HarnessSkillMiddleware — 技能加载与策划
  6. AsyncToolMiddleware — 异步工具执行
  7. CompactionMiddleware — 上下文溢出压缩
  8. ToolResultEvictionMiddleware — 旧工具结果淘汰
  9. MemoryFlushMiddleware — 记忆持久化
  10. MemoryMaintenanceMiddleware — 定期记忆维护
  11. SandboxLifecycleMiddleware — 沙箱生命周期
  12. AgentTraceMiddleware — OpenTelemetry 追踪
  13. AtPathExpansionMiddleware — @ 路径展开

6.3 agentscope-extensions — 扩展模块

模块组织方式：扩展不再扁平排列，而是按功能域分为 19 个分组父模块，每个父模块可包含若干子模块。

6.3.1 模型供应商 (agentscope-extensions-model/)

子模块 用途 关键依赖
agentscope-extensions-model-openai OpenAI / DeepSeek / GLM 等 OkHttp（自实现 HTTP 客户端）
agentscope-extensions-model-dashscope 阿里云 DashScope (通义千问) OkHttp
agentscope-extensions-model-gemini Google Gemini Google GenAI SDK
agentscope-extensions-model-anthropic Anthropic Claude Anthropic Java SDK
agentscope-extensions-model-ollama Ollama 本地模型 OkHttp
agentscope-extensions-model-e2e-tests 模型端到端测试 以上全部

模型供应商通过实现 ModelProvider SPI 接口注册到 ModelRegistry，使用 ServiceLoader 机制发现。

6.3.2 协议扩展 (agentscope-extensions-protocol/)

子模块 用途
agentscope-extensions-a2a Google Agent-to-Agent 协议父模块
agentscope-extensions-a2a-client A2A 客户端
agentscope-extensions-a2a-server A2A 服务端
agentscope-extensions-agent-protocol Agent 协议（依赖 harness）
agentscope-extensions-agui AG-UI Web 界面协议
agentscope-extensions-chat-completions-web Chat Completions REST API

6.3.3 RAG 后端 (agentscope-extensions-rag/)

子模块 用途 关键依赖
agentscope-extensions-rag-simple 最完整的本地 RAG 实现 Qdrant, Milvus, Elasticsearch, PostgreSQL/pgvector, PDFBox, POI, Tika
agentscope-extensions-rag-bailian 阿里云百炼知识库 Bailian SDK
agentscope-extensions-rag-dify Dify 知识库 OkHttp
agentscope-extensions-rag-ragflow RAGFlow 知识库 OkHttp
agentscope-extensions-rag-haystack HayStack 知识库 OkHttp

6.3.4 记忆扩展 (agentscope-extensions-mem/)

子模块 用途
agentscope-extensions-mem0 Mem0 记忆服务
agentscope-extensions-memory-bailian 阿里云百炼长期记忆
agentscope-extensions-reme ReMe 记忆服务

另有 agentscope-extensions-autocontext-memory 作为独立的 AutoContext 记忆模块。

6.3.5 通道集成 (agentscope-extensions-channel/)

子模块 用途
agentscope-extensions-channel-common 通道通用抽象
agentscope-extensions-channel-dingtalk 钉钉集成
agentscope-extensions-channel-feishu 飞书 / Lark 集成
agentscope-extensions-channel-wecom 企业微信集成
agentscope-extensions-channel-github GitHub Issues/PR 集成
agentscope-extensions-channel-gitlab GitLab Issues/MR 集成

6.3.6 沙箱后端 (agentscope-extensions-sandbox/)

子模块 用途
agentscope-extensions-sandbox-kubernetes K8s 沙箱
agentscope-extensions-sandbox-agentrun AgentRun 沙箱
agentscope-extensions-sandbox-daytona Daytona 沙箱
agentscope-extensions-sandbox-e2b E2B 沙箱

Docker 沙箱保留在 agentscope-harness 中，其他沙箱后端作为扩展。

6.3.7 调度器 (agentscope-extensions-scheduler/)

子模块 用途
agentscope-extensions-scheduler-common 调度 SPI
agentscope-extensions-scheduler-quartz Quartz 调度器
agentscope-extensions-scheduler-xxl-job XXL-JOB 调度器

6.3.8 状态存储扩展

独立模块 用途 关键依赖
agentscope-extensions-redis Redis AgentState 存储 Redisson / Jedis / Lettuce
agentscope-extensions-mysql MySQL AgentState 存储 MySQL Connector
agentscope-extensions-postgresql PostgreSQL AgentState 存储 (含 pgvector) PostgreSQL JDBC
agentscope-extensions-oss 阿里云 OSS 状态存储 Aliyun OSS SDK
agentscope-extensions-cos 腾讯云 COS 状态存储 COS SDK
agentscope-extensions-session-redis Redis 会话存储 Redisson / Jedis / Lettuce
agentscope-extensions-session-mysql MySQL 会话存储 MySQL Connector

6.3.9 技能仓库 (agentscope-extensions-skills/)

子模块 用途
agentscope-extensions-skill-git-repository Git 仓库技能存储
agentscope-extensions-skill-mysql-repository MySQL 技能存储
agentscope-extensions-skill-postgresql-repository PostgreSQL 技能存储

6.3.10 Nacos 集成 (agentscope-extensions-nacos/)

子模块 用途
agentscope-extensions-nacos-a2a Nacos 服务发现 + A2A 注册
agentscope-extensions-nacos-prompt Nacos Prompt 管理
agentscope-extensions-nacos-skill Nacos 技能注册

6.3.11 其他独立扩展

模块 用途
agentscope-extensions-higress Higress AI 网关集成
agentscope-extensions-studio AgentScope Studio 追踪
agentscope-extensions-training 训练数据生成
agentscope-extensions-rocketmq RocketMQ + A2A 消息队列集成
agentscope-extensions-autocontext-memory AutoContext 记忆
agentscope-extensions-kotlin Kotlin 协程桥接

6.3.12 Spring Boot Starters (10 个)

Starter 用途
agentscope-spring-boot-starter 核心 Starter — AgentscopeAutoConfiguration, Agent/Model 属性自动配置
agentscope-openai-spring-boot-starter 预注册 OpenAI 模型工厂
agentscope-dashscope-spring-boot-starter 预注册 DashScope 模型工厂
agentscope-gemini-spring-boot-starter 预注册 Gemini 模型工厂
agentscope-anthropic-spring-boot-starter 预注册 Anthropic 模型工厂
agentscope-a2a-spring-boot-starter A2A 协议自动配置
agentscope-agui-spring-boot-starter AG-UI Web 界面
agentscope-chat-completions-web-starter Chat Completions REST API
agentscope-admin-spring-boot-starter Admin 管理界面
agentscope-nacos-spring-boot-starter Nacos 自动配置

6.3.13 框架集成

模块 框架 内部结构
agentscope-micronaut-extensions Micronaut agentscope-micronaut-extension
agentscope-quarkus-extensions Quarkus agentscope-quarkus-extension + agentscope-quarkus-extension-deployment

6.4 agentscope-dependencies-bom — 外部依赖版本管理

集中管理所有第三方库版本的关键依赖：

类别 核心库 版本
LLM SDK DashScope SDK, OpenAI Java, Google GenAI, Anthropic Java, Bailian SDK 2.22.9 / 4.28.0 / 1.45.0 / 2.14.0 / 2.8.2
AI 协议 MCP SDK, A2A SDK 0.17.0 / 0.3.3.Final
响应式 Reactor BOM 2025.0.2
序列化 Jackson, SnakeYAML 2.21.1 / 2.6
HTTP OkHttp 5.3.2
JSON Schema victools jsonschema-generator, networknt json-schema-validator 4.38.0 / 2.0.0
向量数据库 Qdrant, Milvus, Elasticsearch, pgvector 1.17.0 / 2.6.17 / 9.3.3 / 0.1.6
数据库 MySQL Connector, PostgreSQL, SQLite 9.6.0 / 42.7.11 / —
缓存/会话 Redisson, Jedis, Lettuce 4.2.0 / 7.4.1 / 6.4.2
调度 Quartz, XXL-JOB 2.5.2 / 3.3.2
Spring Spring Framework, Spring Boot 7.0.7 / 4.0.4
文档处理 PDFBox, POI, Tika 3.0.7 / 5.5.1 / 3.3.0
可观测性 OpenTelemetry 1.61.0
基础设施 Kubernetes Client, Protobuf, Nacos Client, JGit 6.13.4 / 4.29.3 / 3.2.1 / 7.6.0
代码安全 tree-sitter, tree-sitter-bash 0.24.4 / —

6.5 agentscope-distribution — 打包分发

子模块 Artifact ID 用途
agentscope-all agentscope Shaded uber-JAR，通过 maven-shade-plugin 将 core + harness + 全部 extensions 合并为一个 JAR
agentscope-bom agentscope-bom BOM POM，列出所有内部模块版本，下游消费者统一管理

6.6 agentscope-examples — 示例项目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
agentscope-examples/
├── agents/                        # Agent 示例
│   ├── agentscope-builder         # Builder 模式构建 Agent
│   ├── agentscope-paw             # PAW (Plan-Act-Workspace) Agent
│   ├── agentscope-codingagent     # 编程 Agent
│   ├── agentscope-dataagent       # 数据分析 Agent
│   ├── agentscope-claw            # CLAW Agent
│   └── boba-tea-shop              # 奶茶店（趣味示例）
├── integration/                   # 集成示例
│   ├── a2a-rocketmq               # A2A + RocketMQ
│   ├── agui                       # AG-UI
│   ├── micronaut                  # Micronaut 集成
│   └── quarkus                    # Quarkus 集成
├── multiagent-patterns/           # 多 Agent 协作模式
│   ├── handoffs                   # 任务交接模式
│   ├── pipeline                   # 管道模式
│   ├── routing                    # 路由模式
│   ├── skills                     # 技能模式
│   ├── subagent                   # 子 Agent 模式
│   ├── supervisor                 # 监督者模式
│   └── workflow                   # 工作流模式
└── documentation/                 # 文档示例

7. 完整依赖图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
agentscope-dependencies-bom (外部版本)
       │
       v
   agentscope-parent (根)
      │
      ├── agentscope-core (零内部依赖)
      │     │
      │     ├── agentscope-harness
      │     │     │
      │     │     └── agentscope-extensions-agent-protocol
      │     │
      │     ├── [所有扩展分组模块 —— 均依赖 core]
      │     │     │
      │     │     ├── agentscope-extensions-model/
      │     │     │     ├── model-openai, model-dashscope, model-gemini
      │     │     │     ├── model-anthropic, model-ollama
      │     │     │     └── model-e2e-tests
      │     │     │
      │     │     ├── agentscope-extensions-protocol/
      │     │     │     ├── extensions-a2a (client + server)
      │     │     │     ├── extensions-agent-protocol
      │     │     │     ├── extensions-agui
      │     │     │     └── extensions-chat-completions-web
      │     │     │
      │     │     ├── agentscope-extensions-rag/
      │     │     │     └── rag-{simple, bailian, dify, ragflow, haystack}
      │     │     │
      │     │     ├── agentscope-extensions-mem/
      │     │     │     └── mem0, memory-bailian, reme
      │     │     │
      │     │     ├── agentscope-extensions-channel/
      │     │     │     └── channel-{common, dingtalk, feishu, wecom, github, gitlab}
      │     │     │
      │     │     ├── agentscope-extensions-sandbox/
      │     │     │     └── sandbox-{kubernetes, agentrun, daytona, e2b}
      │     │     │
      │     │     ├── agentscope-extensions-scheduler/
      │     │     │     └── scheduler-{common, quartz, xxl-job}
      │     │     │
      │     │     ├── agentscope-extensions-skills/
      │     │     │     └── skill-{git, mysql, postgresql}-repository
      │     │     │
      │     │     ├── agentscope-extensions-nacos/
      │     │     │     └── nacos-{a2a, prompt, skill}
      │     │     │
      │     │     ├── [独立扩展]
      │     │     │     ├── extensions-redis, extensions-mysql, extensions-postgresql
      │     │     │     ├── extensions-oss, extensions-cos
      │     │     │     ├── extensions-session-redis, extensions-session-mysql
      │     │     │     ├── extensions-higress, extensions-studio
      │     │     │     ├── extensions-training, extensions-kotlin
      │     │     │     ├── extensions-rocketmq
      │     │     │     └── extensions-autocontext-memory
      │     │     │
      │     │     ├── agentscope-spring-boot-starters/ (10 个)
      │     │     ├── agentscope-micronaut-extensions/
      │     │     └── agentscope-quarkus-extensions/
      │     │
      │     ├── agentscope-distribution
      │     │     ├── agentscope-all (shaded JAR, 包含 core + harness + 全部 extensions)
      │     │     └── agentscope-bom (内部模块版本 BOM)
      │     │
      │     └── agentscope-examples
      │           ├── agents/ (builder, paw, codingagent, dataagent, claw, boba-tea-shop)
      │           ├── integration/ (a2a-rocketmq, agui, micronaut, quarkus)
      │           ├── multiagent-patterns/ (handoffs, pipeline, routing, skills, subagent, supervisor, workflow)
      │           └── documentation/

8. 架构设计要点总结

  1. Core 是纯粹的核心抽象：Agent 模型、消息系统、工具体系、中间件链、状态管理、权限引擎，零内部依赖，是整个框架唯一的基础

  2. v2 架构三大支柱：

    • Middleware (中间件链) — 替代旧 Hook 体系，提供 onAgent/onReasoning/onActing/onModelCall/onSystemPrompt 五个插入点
    • AgentState (状态管理) — per-session per-user 运行时状态容器，统一管理上下文、权限、工具、任务、Plan Mode 状态
    • Fine-grained Events (细粒度事件) — 34 种 AgentEvent 类型，完整覆盖 Agent 执行生命周期的每个细节

  3. Harness 提供生产级运行时：HarnessAgent 带有 14 个内置中间件的完整运行时栈，工作区管理、技能策划（curator/promoter/gate）、对话压缩、子 Agent 编排等生产级能力

  4. 模型供应商 SPI 插件化：模型供应商从 Core 中完全解耦为独立扩展模块，通过 ModelProvider SPI + ServiceLoader 自动发现，支持 5 种 LLM 供应商 + 任意兼容 OpenAI API 的服务

  5. Extensions 功能域分组管理：~50 个子模块按功能域分为 19 个分组父 POM（model/rag/mem/channel/sandbox/scheduler/nacos/skills/protocol），结构清晰，按需引入

  6. agentscope-all 提供一站式依赖：Shaded uber-JAR 将 core + harness + 全部 extensions 合并为一个 artifact，简化消费者的依赖管理

  7. 多框架集成：Spring Boot 10 个 Starter（含 per-model Starter）、Micronaut 扩展、Quarkus 扩展（runtime + deployment）

  8. 多 LLM 厂商支持：OpenAI（兼容 DeepSeek/GLM）、DashScope（通义千问）、Gemini、Anthropic（Claude）、Ollama 本地模型

  9. A2A 协议深度集成：Google Agent-to-Agent 协议全链路支持（客户端/服务端/RocketMQ 传输/Nacos 服务发现/Spring Boot 自动配置）

  10. 丰富的协作通道：钉钉、飞书、企业微信、GitHub、GitLab 五大通道集成，支持多 Agent 协作场景

  11. 阿里云 + 腾讯云生态：DashScope、百炼（记忆/RAG）、Nacos、OSS、RocketMQ + 腾讯云 COS，覆盖国内两大云厂商