# agentscope-ai/agentscope-java architecture

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

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

## Overview

AgentScope Java is a framework for building long-running, controllable agents, with a separate service product for observing, registering, and orchestrating agents. The principal workflow accepts a user message through a HarnessAgent, runs the ReAct reasoning/tool loop against a configured model, and returns a result; events support streaming and human oversight. The repository also documents permissions, middleware, sandboxed workspaces, multi-agent orchestration, and distributed session recovery. Several subsystem links below are documented capabilities rather than verified calls because their implementations were not sampled.

Main entry points: [`agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java`](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java) (Harness agent), [`agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java`](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java) (ReAct loop), [`agentscope-service/service-controlplane/internal/orchestration/engine.go`](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-service/service-controlplane/internal/orchestration/engine.go) (Control plane), [`agentscope-core/src/main/java/io/agentscope/core/session/SessionLog.java`](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/session/SessionLog.java) (Session log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_harness["Harness agent<br/>[HarnessAgent.java]"]
  node_react["ReAct loop<br/>[ReActAgent.java]"]
  node_agent_api["Agent API<br/>[Agent.java]"]
  node_runtime_context["Runtime context"]
  node_messages["Messages<br/>[Msg.java]"]
  node_model["Model interface<br/>[Model.java]"]
  node_model_provider["Model provider"]
end

subgraph group_execution["Execution controls"]
  node_events["Typed events<br/>[AgentEvent.java]"]
  node_permissions["Permission engine"]
  node_middleware["Middleware"]
  node_workspace["Workspace and sandbox"]
  node_subagents["Subagent orchestration"]
end

subgraph group_persistence["Sessions and state"]
  node_session_log[("Session log<br/>[SessionLog.java]")]
  node_atomic_storage["Atomic storage API"]
  node_sqlite_storage[("SQLite storage")]
end

subgraph group_service["Agent service"]
  node_controlplane["Control plane<br/>[engine.go]"]
  node_runtimehost["Runtime host<br/>[engine.go]"]
  node_service_dashboard["Service dashboard<br/>[main.tsx]"]
  node_session_events[("Session event log")]
end

node_user(("User"))
node_model_service(("Model service"))
node_distributed_backend[("Distributed storage")]

node_user -->|"submits message"| node_harness
node_harness -.->|"runs agent"| node_react
node_react -.->|"requests completion"| node_model
node_model -.->|"uses provider"| node_model_provider
node_model_provider -.->|"calls model"| node_model_service
node_harness -->|"accepts input"| node_messages
node_harness -->|"uses context"| node_runtime_context
node_react -->|"streams events"| node_events
node_react -->|"gates tools"| node_permissions
node_react -->|"supports interception"| node_middleware
node_harness -->|"uses workspace"| node_workspace
node_react -->|"supports orchestration"| node_subagents
node_harness -->|"persists sessions"| node_session_log
node_session_log -.->|"uses storage contract"| node_atomic_storage
node_atomic_storage -->|"implemented by"| node_sqlite_storage
node_distributed_backend -->|"enables recovery"| node_session_log
node_service_dashboard -.->|"uses service"| node_controlplane
node_controlplane -.->|"coordinates runtime"| node_runtimehost
node_controlplane -.->|"supports observation"| node_session_events

click node_harness "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java"
click node_react "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java"
click node_agent_api "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java"
click node_runtime_context "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/agent/RuntimeContext.java"
click node_messages "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/message/Msg.java"
click node_model "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/model/Model.java"
click node_model_provider "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/DashScopeHttpClient.java"
click node_events "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/event/AgentEvent.java"
click node_permissions "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/permission/PermissionEngine.java"
click node_middleware "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/middleware/MiddlewareChain.java"
click node_workspace "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-harness/src/main/java/io/agentscope/harness/agent/workspace/WorkspaceManager.java"
click node_subagents "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/agent/SubagentEventBus.java"
click node_session_log "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/session/SessionLog.java"
click node_atomic_storage "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/session/AtomicSessionStorage.java"
click node_sqlite_storage "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-harness/src/main/java/io/agentscope/harness/agent/session/SqliteSessionStorage.java"
click node_controlplane "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-service/service-controlplane/internal/orchestration/engine.go"
click node_runtimehost "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-service/service-controlplane/internal/runtimehost/engine.go"
click node_service_dashboard "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-service/frontend/src/main.tsx"
click node_session_events "https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-service/service-common/src/main/java/io/agentscope/builder/web/managed/service/SessionEventLog.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_harness,node_react,node_agent_api,node_runtime_context,node_messages,node_model,node_model_provider,node_user toneBlue
class node_events,node_permissions,node_middleware,node_workspace,node_subagents,node_distributed_backend toneAmber
class node_session_log,node_atomic_storage,node_sqlite_storage toneMint
class node_controlplane,node_runtimehost,node_service_dashboard,node_session_events toneRose
class node_model_service toneIndigo
```

## Components

### Agent runtime

- [Harness agent](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java): `agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java`
- [ReAct loop](https://github.com/agentscope-ai/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 API](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java): `agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java`
- [Runtime context](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/agent/RuntimeContext.java): `agentscope-core/src/main/java/io/agentscope/core/agent/RuntimeContext.java`
- [Messages](https://github.com/agentscope-ai/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`
- [Model interface](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/model/Model.java): `agentscope-core/src/main/java/io/agentscope/core/model/Model.java`
- [Model provider](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/DashScopeHttpClient.java): `agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-dashscope/src/main/java/io/agentscope/extensions/model/dashscope/DashScopeHttpClient.java`

### Execution controls

- [Typed events](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/event/AgentEvent.java): `agentscope-core/src/main/java/io/agentscope/core/event/AgentEvent.java`
- [Permission engine](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/permission/PermissionEngine.java): `agentscope-core/src/main/java/io/agentscope/core/permission/PermissionEngine.java`
- [Middleware](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/middleware/MiddlewareChain.java): `agentscope-core/src/main/java/io/agentscope/core/middleware/MiddlewareChain.java`
- [Workspace and sandbox](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-harness/src/main/java/io/agentscope/harness/agent/workspace/WorkspaceManager.java): `agentscope-harness/src/main/java/io/agentscope/harness/agent/workspace/WorkspaceManager.java`
- [Subagent orchestration](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/agent/SubagentEventBus.java): `agentscope-core/src/main/java/io/agentscope/core/agent/SubagentEventBus.java`

### Sessions and state

- [Session log](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/session/SessionLog.java): `agentscope-core/src/main/java/io/agentscope/core/session/SessionLog.java`
- [Atomic storage API](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-core/src/main/java/io/agentscope/core/session/AtomicSessionStorage.java): `agentscope-core/src/main/java/io/agentscope/core/session/AtomicSessionStorage.java`
- [SQLite storage](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-harness/src/main/java/io/agentscope/harness/agent/session/SqliteSessionStorage.java): `agentscope-harness/src/main/java/io/agentscope/harness/agent/session/SqliteSessionStorage.java`

### Agent service

- [Control plane](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-service/service-controlplane/internal/orchestration/engine.go): `agentscope-service/service-controlplane/internal/orchestration/engine.go`
- [Runtime host](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-service/service-controlplane/internal/runtimehost/engine.go): `agentscope-service/service-controlplane/internal/runtimehost/engine.go`
- [Service dashboard](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-service/frontend/src/main.tsx): `agentscope-service/frontend/src/main.tsx`
- [Session event log](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-service/service-common/src/main/java/io/agentscope/builder/web/managed/service/SessionEventLog.java): `agentscope-service/service-common/src/main/java/io/agentscope/builder/web/managed/service/SessionEventLog.java`

### Other components

- **User**
- **Model service**
- **Distributed storage**

## Connections

- User → Harness agent: submits message (evidence: `README.md`)
- Harness agent → ReAct loop: runs agent (evidence: `agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java`)
- ReAct loop → Model interface: requests completion
- Model interface → Model provider: uses provider
- Model provider → Model service: calls model
- Harness agent → Messages: accepts input (evidence: `README.md`)
- Harness agent → Runtime context: uses context (evidence: `README.md`)
- ReAct loop → Typed events: streams events (evidence: `README.md`)
- ReAct loop → Permission engine: gates tools (evidence: `README.md`)
- ReAct loop → Middleware: supports interception (evidence: `README.md`)
- Harness agent → Workspace and sandbox: uses workspace (evidence: `README.md`)
- ReAct loop → Subagent orchestration: supports orchestration (evidence: `README.md`)
- Harness agent → Session log: persists sessions (evidence: `README.md`)
- Session log → Atomic storage API: uses storage contract
- Atomic storage API → SQLite storage: implemented by (evidence: `agentscope-harness/src/main/java/io/agentscope/harness/agent/session/SqliteSessionStorage.java`)
- Distributed storage → Session log: enables recovery (evidence: `README.md`)
- Service dashboard → Control plane: uses service
- Control plane → Runtime host: coordinates runtime
- Control plane → Session event log: supports observation