# albertowang/agentscope-java architecture

> Architecture diagram of the GitHub repository albertowang/agentscope-java, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/albertowang/agentscope-java
- Repository: https://github.com/albertowang/agentscope-java

## Overview

AgentScope Java is a framework for building LLM-powered agents. The main workflow accepts a user message, runs a ReAct agent that reasons with a model and may invoke tools, then returns a response; pipelines support coordinated agent execution. Core layers also cover provider-specific message formatting, memory, planning, retrieval, structured output, hooks and interruption. The README documents additional A2A integration and production capabilities. The tree and excerpts support these subsystem boundaries, but do not establish every runtime call path, so uncertain wiring is omitted.

Main entry points: [`agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java`](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java) (ReAct agent), [`agentscope-core/src/main/java/io/agentscope/core/model/ChatModelBase.java`](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/model/ChatModelBase.java) (Chat models), [`agentscope-core/src/main/java/io/agentscope/core/rag/Knowledge.java`](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/rag/Knowledge.java) (Knowledge retrieval), [`agentscope-core/src/main/java/io/agentscope/core/shutdown/GracefulShutdownManager.java`](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/shutdown/GracefulShutdownManager.java) (Graceful shutdown)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_runtime["Agent runtime"]
  node_react["ReAct agent<br/>[ReActAgent.java]"]
  node_pipelines["Agent pipelines<br/>[Pipelines.java]"]
  node_agent_base["Agent runtime base<br/>[AgentBase.java]"]
  node_messages["Messages<br/>[Msg.java]"]
  node_tool_groups["Tool groups"]
end

subgraph group_model_io["Model integration"]
  node_chat_model["Chat models<br/>[ChatModelBase.java]"]
  node_formatters["Provider formatters<br/>[Formatter.java]"]
end

subgraph group_agent_capabilities["Agent capabilities"]
  node_memory["Memory<br/>[Memory.java]"]
  node_long_memory["Long-term memory"]
  node_planning["Plan notebook<br/>[PlanNotebook.java]"]
  node_plan_storage[("Plan storage<br/>[PlanStorage.java]")]
  node_rag["Knowledge retrieval<br/>[Knowledge.java]"]
end

subgraph group_operations["Runtime operations"]
  node_hooks["Hooks and oversight<br/>[Hook.java]"]
  node_interruptions["Safe interruption"]
  node_shutdown["Graceful shutdown"]
  node_sessions[("Session state<br/>[Session.java]")]
end

subgraph group_integrations["External integrations"]
  node_model_service(("LLM provider"))
  node_dify["Dify RAG<br/>[DifyRAGClient.java]"]
  node_ragflow["RAGFlow<br/>[RAGFlowClient.java]"]
  node_a2a_registry["A2A registry service"]
  node_agent_registry[("Agent registry")]
  node_chat_client(("Chat client"))
end

node_user(("User"))

node_user -->|"sends prompt"| node_react
node_react -->|"runs agent"| node_agent_base
node_react -->|"requests reasoning"| node_chat_model
node_chat_model -->|"formats requests"| node_formatters
node_chat_model -->|"calls model"| node_model_service
node_react -->|"uses tools"| node_tool_groups
node_react -->|"uses memory"| node_memory
node_memory -.->|"supports persistence"| node_long_memory
node_react -->|"manages plans"| node_planning
node_planning -->|"stores plans"| node_plan_storage
node_react -.->|"retrieves knowledge"| node_rag
node_rag -.->|"queries service"| node_dify
node_rag -.->|"queries service"| node_ragflow
node_react -->|"emits lifecycle events"| node_hooks
node_hooks -->|"supports intervention"| node_interruptions
node_shutdown -->|"interrupts requests"| node_interruptions
node_shutdown -->|"saves state"| node_sessions
node_pipelines -->|"dispatches agents"| node_agent_base
node_a2a_registry -->|"registers agent"| node_agent_registry
node_chat_client -.->|"streams requests"| node_react
node_react -->|"returns response"| node_messages

click node_react "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java"
click node_pipelines "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/pipeline/Pipelines.java"
click node_agent_base "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/agent/AgentBase.java"
click node_messages "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java"
click node_tool_groups "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/tool/ToolGroupManager.java"
click node_chat_model "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/model/ChatModelBase.java"
click node_formatters "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/formatter/Formatter.java"
click node_memory "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/memory/Memory.java"
click node_long_memory "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/memory/LongTermMemory.java"
click node_planning "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/plan/PlanNotebook.java"
click node_plan_storage "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/plan/storage/PlanStorage.java"
click node_rag "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/rag/Knowledge.java"
click node_dify "https://github.com/albertowang/agentscope-java/blob/main/agentscope-extensions/agentscope-extensions-rag-dify/src/main/java/io/agentscope/core/rag/integration/dify/DifyRAGClient.java"
click node_ragflow "https://github.com/albertowang/agentscope-java/blob/main/agentscope-extensions/agentscope-extensions-rag-ragflow/src/main/java/io/agentscope/core/rag/integration/ragflow/RAGFlowClient.java"
click node_hooks "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/hook/Hook.java"
click node_interruptions "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/interruption/InterruptContext.java"
click node_shutdown "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/shutdown/GracefulShutdownManager.java"
click node_sessions "https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/session/Session.java"
click node_a2a_registry "https://github.com/albertowang/agentscope-java/blob/main/agentscope-extensions/agentscope-extensions-a2a/agentscope-extensions-a2a-server/src/main/java/io/agentscope/core/a2a/server/registry/AgentRegistryService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_react,node_pipelines,node_agent_base,node_messages,node_tool_groups,node_user toneBlue
class node_chat_model,node_formatters toneAmber
class node_memory,node_long_memory,node_planning,node_plan_storage,node_rag toneMint
class node_hooks,node_interruptions,node_shutdown,node_sessions toneRose
class node_model_service,node_dify,node_ragflow,node_a2a_registry,node_agent_registry,node_chat_client toneIndigo
```

## Components

### Agent runtime

- [ReAct agent](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java): `agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java`
- [Agent pipelines](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/pipeline/Pipelines.java): `agentscope-core/src/main/java/io/agentscope/core/pipeline/Pipelines.java`
- [Agent runtime base](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/agent/AgentBase.java): `agentscope-core/src/main/java/io/agentscope/core/agent/AgentBase.java`
- [Messages](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java): `agentscope-core/src/main/java/io/agentscope/core/message/Msg.java`
- [Tool groups](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/tool/ToolGroupManager.java): `agentscope-core/src/main/java/io/agentscope/core/tool/ToolGroupManager.java`

### Model integration

- [Chat models](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/model/ChatModelBase.java): `agentscope-core/src/main/java/io/agentscope/core/model/ChatModelBase.java`
- [Provider formatters](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/formatter/Formatter.java): `agentscope-core/src/main/java/io/agentscope/core/formatter/Formatter.java`

### Agent capabilities

- [Memory](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/memory/Memory.java): `agentscope-core/src/main/java/io/agentscope/core/memory/Memory.java`
- [Long-term memory](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/memory/LongTermMemory.java): `agentscope-core/src/main/java/io/agentscope/core/memory/LongTermMemory.java`
- [Plan notebook](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/plan/PlanNotebook.java): `agentscope-core/src/main/java/io/agentscope/core/plan/PlanNotebook.java`
- [Plan storage](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/plan/storage/PlanStorage.java): `agentscope-core/src/main/java/io/agentscope/core/plan/storage/PlanStorage.java`
- [Knowledge retrieval](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/rag/Knowledge.java): `agentscope-core/src/main/java/io/agentscope/core/rag/Knowledge.java`

### Runtime operations

- [Hooks and oversight](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/hook/Hook.java): `agentscope-core/src/main/java/io/agentscope/core/hook/Hook.java`
- [Safe interruption](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/interruption/InterruptContext.java): `agentscope-core/src/main/java/io/agentscope/core/interruption/InterruptContext.java`
- [Graceful shutdown](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/shutdown/GracefulShutdownManager.java): `agentscope-core/src/main/java/io/agentscope/core/shutdown/GracefulShutdownManager.java`
- [Session state](https://github.com/albertowang/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/session/Session.java): `agentscope-core/src/main/java/io/agentscope/core/session/Session.java`

### External integrations

- **LLM provider**
- [Dify RAG](https://github.com/albertowang/agentscope-java/blob/main/agentscope-extensions/agentscope-extensions-rag-dify/src/main/java/io/agentscope/core/rag/integration/dify/DifyRAGClient.java): `agentscope-extensions/agentscope-extensions-rag-dify/src/main/java/io/agentscope/core/rag/integration/dify/DifyRAGClient.java`
- [RAGFlow](https://github.com/albertowang/agentscope-java/blob/main/agentscope-extensions/agentscope-extensions-rag-ragflow/src/main/java/io/agentscope/core/rag/integration/ragflow/RAGFlowClient.java): `agentscope-extensions/agentscope-extensions-rag-ragflow/src/main/java/io/agentscope/core/rag/integration/ragflow/RAGFlowClient.java`
- [A2A registry service](https://github.com/albertowang/agentscope-java/blob/main/agentscope-extensions/agentscope-extensions-a2a/agentscope-extensions-a2a-server/src/main/java/io/agentscope/core/a2a/server/registry/AgentRegistryService.java): `agentscope-extensions/agentscope-extensions-a2a/agentscope-extensions-a2a-server/src/main/java/io/agentscope/core/a2a/server/registry/AgentRegistryService.java`
- **Agent registry**
- **Chat client**

### Other components

- **User**

## Connections

- User → ReAct agent: sends prompt
- ReAct agent → Agent runtime base: runs agent
- ReAct agent → Chat models: requests reasoning
- Chat models → Provider formatters: formats requests
- Chat models → LLM provider: calls model
- ReAct agent → Tool groups: uses tools
- ReAct agent → Memory: uses memory
- Memory → Long-term memory: supports persistence
- ReAct agent → Plan notebook: manages plans
- Plan notebook → Plan storage: stores plans
- ReAct agent → Knowledge retrieval: retrieves knowledge
- Knowledge retrieval → Dify RAG: queries service
- Knowledge retrieval → RAGFlow: queries service
- ReAct agent → Hooks and oversight: emits lifecycle events
- Hooks and oversight → Safe interruption: supports intervention
- Graceful shutdown → Safe interruption: interrupts requests
- Graceful shutdown → Session state: saves state
- Agent pipelines → Agent runtime base: dispatches agents
- A2A registry service → Agent registry: registers agent
- Chat client → ReAct agent: streams requests
- ReAct agent → Messages: returns response