Quickly Build Enterprise Self‑Evolving Agents with AgentScope Builder and Harness Framework

AgentScope Java 1.1.0 introduces the HarnessAgent runtime, AbstractFilesystem and a composable CompositeFilesystem that together allow developers to write an agent once and deploy it in multiple forms – from a single‑machine personal assistant (named MinQwenPaw) to an enterprise‑grade multi‑tenant platform (AgentScope Builder).

Two concrete components

agentscope-claw – a lightweight Spring Boot demo that packages a Java version of QwenPaw. It runs locally, stores its state under ~/.agentscope/, and demonstrates three core capabilities: workspace‑driven self‑evolution, direct file‑system and shell access, and integration with chat channels (DingTalk, Feishu, etc.).

agentscope-builder – a web‑based platform that extends the same runtime with a CompositeFilesystem layer, providing per‑user/agent namespace isolation, sharing policies (run / edit / fork), and the ability to run agents in Docker sandboxes or on distributed KV stores.

MinQwenPaw – the personal‑assistant prototype

All agent state is kept in a workspace rather than a database. The workspace contains files such as AGENTS.md (personality and system prompt), skills/ (reusable tools), subagents/ (child agents), MEMORY.md (double‑layer memory) and session logs under agents/<subId>/sessions/. After each conversation the agent extracts new facts into MEMORY.md, enabling continuous growth without manual updates.

Why a single‑machine solution does not scale

Multiple users need isolated views of the same agent.

Workspaces must not pollute each other – each user’s memory, skills and sub‑agents must remain private.

In a multi‑replica deployment the same user must see a consistent workspace across nodes.

Running untrusted code (SQL, Python, shell) requires OS‑level isolation.

Builder’s design – workspace as the asset

Builder treats the workspace as the primary asset. Isolation, sharing and multi‑tenant capabilities are built on top of this concept:

Isolation : each (userId, agentId) pair gets its own namespace under users/{userId}/agents/{agentId}/. The agent sees only its own subtree.

Sharing : three permission levels – run (execute without seeing or editing files), edit (modify configuration and files), and fork (copy the workspace for independent evolution).

CompositeFilesystem – how isolation is achieved

The CompositeFilesystem consists of two layers:

Namespace dispatch (top layer) : rewrites any path to users/{userId}/agents/{agentId}/... based on the RuntimeContext (extracted from JWT and request URL).

Physical storage backend (bottom layer) : can be local disk, Docker container, or a remote KV store. By default it uses LocalFilesystemWithShell (writes to ~/.agentscope/builder/workspace/...).

Agent code calls standard file APIs ( read, write, ls, grep) unaware of the two layers; the filesystem abstraction handles namespace isolation and storage selection.

End‑to‑end request walk‑through

Web layer parses JWT to obtain userId and extracts agentId from the URL, creating a RuntimeContext.

Channel router uses (userId, agentId) to select a dedicated HarnessAgent instance.

During inference the agent invokes a tool such as write_file("skills/sql-helper/SKILL.md", …).

The CompositeFilesystem intercepts the call, rewrites the path to users/alice/agents/agent-A/skills/sql-helper/SKILL.md, and forwards it to the storage backend.

On the next turn the agent reads the same workspace files, automatically seeing the newly learned skill.

Sandbox mode for untrusted code

When executing user‑provided scripts, Builder can add a projection layer that runs the agent inside a Docker container. The host still owns the authoritative workspace files ( AGENTS.md, skills/, etc.) which are mounted into the container at /workspace. This isolates shell commands while preserving a consistent view of the workspace.

Distributed storage for multi‑node deployment

To scale beyond a single machine, the bottom storage layer can be swapped for a BaseStore implementation (Redis, OSS/S3, or a custom KV service). All agents and the web UI then read/write the same BaseStore, guaranteeing that every replica sees identical workspace data. Session management can also use a distributed store (e.g., RedisSession).

Overall architecture

┌─────────────────────────────────────────────────────────────────────┐
│  AgentScope Builder (Spring Boot, port 8080)                       │
│   React SPA ──▶ REST API (JWT)                                    │
│        │                                                         │
│        ▼                                                         │
│   ┌───────────────────────────────────────────────┐           │
│   │  Channel routing component                      │           │
│   │   ├─ Agent (alice, agent‑A) ──┐                │           │
│   │   ├─ Agent (alice, agent‑B) │  one HarnessAgent per (user,agent) │
│   │   └─ Agent (bob,   agent‑A) ──┘                │           │
│   └───────────────────────┬───────────────────────┘           │
│                           ▼                               │
│   ┌───────────────────────────────────────────────┐           │
│   │  CompositeFilesystem                           │           │
│   │   ├─ Top layer: namespace dispatch (userId,agentId) → subtree │
│   │   └─ Bottom layer: storage backend (local / sandbox / distributed) │
│   └───────────────────────────────────────────────┘           │
│   User & agent metadata (H2 default, switchable to MySQL/PostgreSQL) │
└─────────────────────────────────────────────────────────────────────┘

Quick start

Claw (personal assistant):

# Set model API key (default DashScope)
export DASHSCOPE_API_KEY=sk-xxx
# Build and run
mvn -pl agentscope-examples/agents/agentscope-claw -am clean package -DskipTests
java -jar agentscope-examples/agents/agentscope-claw/target/agentscope-claw-*.jar
# Open http://localhost:8080 (workspace at ~/.agentscope)

Builder (team platform):

export DASHSCOPE_API_KEY=sk-xxx
mvn -pl agentscope-examples/agents/agentscope-builder -am clean package -DskipTests
java -jar agentscope-examples/agents/agentscope-builder/target/agentscope-builder-*.jar
# Login with admin/admin, bob/bob or alice/alice at http://localhost:8080

Claw vs Builder – which to choose?

Both products share the same HarnessAgent runtime; the only difference is the surrounding infrastructure. Use Claw for a personal, single‑machine assistant; use Builder when you need multi‑user isolation, sharing, sandboxing, or distributed deployment. The agent logic itself does not change.

References

AgentScope Java 1.1.0 release and Harness design – https://java.agentscope.io/zh/blogs/agentscope-v1-harness.html

agentscope-claw README – https://github.com/agentscope-ai/agentscope-java/tree/main/agentscope-examples/agents/agentscope-claw

agentscope-builder README – https://github.com/agentscope-ai/agentscope-java/tree/main/agentscope-examples/agents/agentscope-builder

QwenPaw product page – https://qwenpaw.agentscope.io/