Quick Experience with AgentScope Builder: Building Enterprise Self‑Evolving Agents Using the Harness Framework

AgentScope Builder is a Spring Boot platform that turns the Harness runtime into a multi‑tenant, enterprise‑grade system for self‑evolving AI agents. It builds on the same core components introduced in AgentScope Java 1.1.0— HarnessAgent, AbstractFilesystem, and a double‑layer memory model—while adding a workspace‑centric isolation layer.

MinQwenPaw: a single‑machine prototype

MinQwenPaw is a lightweight Java implementation of QwenPaw that runs on a local machine. It stores all agent state in the directory ~/.agentscope/claw/workspace/ and demonstrates three core capabilities:

Workspace‑driven self‑evolution : the agent writes files such as AGENTS.md, skills/, subagents/, and MEMORY.md to record its persona, learned skills, child agents, and memory.

Direct OS and shell access : using the LocalFilesystemWithShell backend, the agent can execute commands on the host (e.g., moving files in ~/Downloads).

Integration with messaging channels : the agent can be invoked from DingTalk, Feishu, or other IM platforms via the outbound_send tool.

These features work well for a single user on a single host but expose several enterprise challenges: sharing a process among many users, isolating each user’s workspace, keeping memory consistent across replicas, sandboxing untrusted code, and sharing agents without exposing internal state.

Builder: turning the prototype into a multi‑tenant platform

Builder addresses the five challenges by treating the workspace as the primary asset of an agent. It introduces two high‑level capabilities:

Multi‑tenant, distributed version of QwenPaw : each (user, agent) pair gets an isolated workspace namespace users/{userId}/agents/{agentId}/, enabling independent evolution and shared deployment.

Zero‑code intelligent‑agent development platform : users create, configure, and share agents through a web UI without writing code. The UI guides them through template selection, model choice, system‑prompt editing, and skill/agent/tool configuration.

Key design principles:

Workspace is the agent’s asset : all state (persona, skills, memory, sub‑agents) lives in files under the workspace, making it versionable and editable.

Isolation via CompositeFilesystem : a two‑layer filesystem where the upper layer rewrites paths to a user‑agent‑specific namespace ( users/{userId}/agents/{agentId}/…) and the lower layer selects the physical storage backend (local disk, Docker container, or remote KV store).

Channel routing : a router extracts (userId, agentId) from incoming requests and dispatches them to a dedicated HarnessAgent instance, each bound to its own CompositeFilesystem view.

End‑to‑end write flow example

Web layer parses JWT to obtain userId=alice and URL to get agentId=agent‑A, then creates a RuntimeContext for this pair.

Channel router routes the request to Agent(alice, agent‑A) (a HarnessAgent instance).

During inference the agent calls write_file("skills/sql‑helper/SKILL.md", …). CompositeFilesystem intercepts the call, rewrites the path to users/alice/agents/agent‑A/skills/sql‑helper/SKILL.md, and forwards it to the lower‑layer storage.

With the default local backend the file is finally written to

~/.agentscope/builder/workspace/users/alice/agents/agent‑A/skills/sql‑helper/SKILL.md

.

On the next conversation the workspace loader reads the updated skills/ directory, automatically making the new skill available to the agent.

The same process works for other users (e.g., Bob) because the namespace rewrite guarantees complete isolation without any business‑level if (user == "alice") checks in the agent code.

Sandbox mode for untrusted code

When agents need to execute untrusted code (SQL, Python, shell), Builder can add a projection layer that runs the HarnessAgent inside a Docker container. The container sees the same workspace files via a mounted /workspace directory, while all shell commands are confined to the container, protecting the host.

Distributed storage

To scale beyond a single node, the lower storage layer can be swapped for a remote KV store (Redis, OSS, custom service) by implementing the BaseStore interface. All reads/writes then go through RemoteFilesystem, and the web UI and agents share the same data, enabling consistent state across replicas.

Overall architecture

┌─────────────────────────────────────────────────────────────────────┐
│  AgentScope Builder (Spring Boot, port 8080)                       │
│   React SPA ──▶ REST API (JWT)                                    │
│        │                                                         │
│        ▼                                                         │
│   ┌───────────────────────────────────────┐                     │
│   │  Channel routing component            │                     │
│   │   ├─ Agent(alice, agent‑A) ──┐          │                     │
│   │   ├─ Agent(alice, agent‑B) │          │                     │
│   │   └─ Agent(bob,   agent‑A) ──┘          │                     │
│   └───────────────────────┬───────────────┘                     │
│                           ▼                                 │
│   ┌───────────────────────────────────────┐                     │
│   │  CompositeFilesystem                    │                     │
│   │   ├─ Upper layer: namespace dispatch   │                     │
│   │   └─ Lower layer: storage backend     │                     │
│   └───────────────────────────────────────┘                     │
│   User & agent metadata (H2 / MySQL)                              │
└─────────────────────────────────────────────────────────────────────┘

Quick start commands

# Set model API key (default DashScope)
export DASHSCOPE_API_KEY=sk-xxx

# Build and run Claw (single‑machine demo)
mvn -pl agentscope-examples/agents/agentscope-claw -am clean package -DskipTests
java -jar agentscope-examples/agents/agentscope-claw/target/agentscope-claw-*.jar

# Build and run Builder (web UI on port 8080)
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

After starting Builder, log in with admin/admin, alice/alice, or bob/bob to explore the full UI. The default workspace directory is ~/.agentscope; editing ~/.agentscope/agentscope.json adds DingTalk, Feishu, or other channel configurations.

Claw vs. Builder

Both are built on the same Harness runtime, but Claw is a single‑machine, code‑first example, while Builder adds:

Multi‑user isolation via workspace namespaces.

Web‑based zero‑code agent creation, editing, sharing, and forking.

Optional sandboxing and distributed storage for production deployments.

The two can be used together: develop an agent locally with Claw (producing a MinQwenPaw workspace), then copy the workspace directory into Builder to share it across a team.

Conclusion

AgentScope Builder demonstrates how a well‑designed runtime ( HarnessAgent + CompositeFilesystem) can be repurposed from a personal assistant prototype to a full‑featured, multi‑tenant, cloud‑native AI‑agent platform without changing any agent business logic. By treating the workspace as the sole source of truth, the system supports continuous self‑evolution, zero‑code onboarding, fine‑grained sharing permissions, and scalable deployment options.