Why AgentScope 2.0 Is the Ideal Harness Runtime for Managed Agents

Overview

Managed Agents run AI agents in the cloud, separating long‑running tasks from local devices and guaranteeing platform stability. AgentScope 2.0 provides the Harness runtime that isolates execution in a sandbox while delivering a reliable inference and orchestration layer (Brain).

Architecture

Control Plane

The control plane defines what can run and who can use it. It manages static definitions such as Agents, Models, Skills, Tools, MCPs, Environments, Memory, Vaults, and other reusable resources. Resources are versioned, can be shared across tenants, and support ACLs, archiving, and rotation, enabling safe upgrades and rollback.

Data Plane

The data plane materializes a Session (Agent × Environment) and drives the ReAct loop, Harness hooks, turn leases, event persistence, SSE streaming, interrupts, HITL, and tool‑result handling. Each turn records user.message, userId, sessionId, and a RuntimeContext that ties the session state, environment, and user identity together.

Worker

Workers execute the Hands side (file system, shell, custom tools). Three modes are supported:

Local : Development mode where Brain, model calls, and tool execution all run on the managed cluster; files and shells are directly visible to the Brain process.

Cloud Sandbox : Brain stays in the managed cluster, but tool execution is delegated to an isolated sandbox (FC Sandbox/E2B compatible). The sandbox lifecycle (create, run, recycle) is managed by the platform.

Self‑hosted : Hands are moved to the customer’s environment. The Brain posts a tool_use event, the customer’s Worker polls the queue, runs the tool locally or in a private sandbox, and returns the result via user.tool_result. The platform does not directly access the customer network.

Runtime Features

AgentScope 2.0 splits the runtime into Brain (next‑turn inference, state recovery, context management) and Hands (file and network operations). This separation lets security teams answer three questions independently: what context the model sees, what resources the tool can access, and which tool results are fed back to the Brain.

Deployment Walk‑through

Minimal end‑to‑end example using the Java SDK and REST API.

export BASE=http://localhost:8080
TOKEN=$(curl -fsS -X POST "$BASE/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}' | jq -er .token)

Define a Workspace Copilot Agent with read/write file tools:

AGENT=$(curl -fsS -X POST "$BASE/api/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"Workspace Copilot",
    "description":"blog demo agent",
    "system":"You are a workspace copilot. Prefer tools when listing or reading files. Keep answers concise.",
    "tools":[{
      "type":"agent_toolset",
      "defaultConfig":{"enabled":true,"permissionPolicy":{"type":"always_allow"}},
      "configs":[{"name":"read_file","enabled":true},{"name":"list_files","enabled":true},{"name":"write_file","enabled":true}]
    }]
  }')
AGENT_ID=$(echo "$AGENT" | jq -er .id)

echo "AGENT_ID=$AGENT_ID"

Run the same Agent in three worker modes to see that the Agent definition stays unchanged while the Hands location varies:

Local : type=local in the Environment – files live on the managed host.

Cloud Sandbox : Environment points to an E2B‑compatible sandbox; the Brain creates the sandbox and invokes tools via the sandbox API.

Self‑hosted : Environment is type=self_hosted; the Brain emits tool_use, the customer Worker polls, executes, and posts user.tool_result.

Multi‑Agent Orchestration Example

A three‑role team demonstrates composition of Agents:

Repo Surgeon : Read‑only code analysis (tools: read_file, grep_files, list_files).

Ops Publisher : Generates a changelog draft (no tool execution, only system prompt).

Team Lead : Coordinates the two, spawns sub‑sessions, aggregates results, and produces a final checklist.

Creating the agents (simplified):

# Ops Publisher (no tools)
OPS_BODY=$(jq -n '{name:"Ops Publisher",system:"Draft changelogs and ticket outlines. Do not invoke tools.",tools:[]}')
OPS=$(curl -fsS -X POST "$BASE/api/agents" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d "$OPS_BODY")
OPS_ID=$(echo "$OPS" | jq -er .id)

# Repo Surgeon (read‑only tools)
REPO_BODY=$(jq -n '{name:"Repo Surgeon",system:"You review the user workspace in read‑only mode and report release risks.",tools:[{type:"agent_toolset",defaultConfig:{enabled:true,permissionPolicy:{type:"always_allow"}},configs:[{name:"read_file",enabled:true},{name:"grep_files",enabled:true},{name:"list_files",enabled:true}]}]}')
REPO=$(curl -fsS -X POST "$BASE/api/agents" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d "$REPO_BODY")
REPO_ID=$(echo "$REPO" | jq -er .id)

# Team Lead (orchestrator)
LEAD_BODY=$(jq -n --arg repo "$REPO_ID" --arg ops "$OPS_ID" '{
  name:"Team Lead",
  system:"You coordinate Repo Surgeon and Ops Publisher. Spawn sub‑sessions, collect results, and summarize risks. Use sessions_pending_completions and wait_async_results as needed.",
  tools:[{type:"agent_toolset",defaultConfig:{enabled:true,permissionPolicy:{type:"always_allow"}},configs:[{name:"sessions_spawn",enabled:true},{name:"sessions_list",enabled:true},{name:"sessions_pending_completions",enabled:true},{name:"wait_async_results",enabled:true}]}],
  multiagent:{type:"agent_team",agents:[{type:"agent",id:$repo},{type:"agent",id:$ops}]}
}')
LEAD=$(curl -fsS -X POST "$BASE/api/agents" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d "$LEAD_BODY")
LEAD_ID=$(echo "$LEAD" | jq -er .id)

echo "OPS_ID=$OPS_ID REPO_ID=$REPO_ID LEAD_ID=$LEAD_ID"

The orchestrator can either use Harness native delegation ( sessions_spawn) or the platform fan‑out API ( /api/multiagent/run) to run the sub‑agents in parallel.

Key Takeaways

Versioned Agent definitions with shared Skills and Tools.

Multi‑tenant ACLs and resource isolation.

Persistent session state and turn leases for long‑running tasks.

Pluggable sandbox abstractions that let Hands run locally, in a cloud sandbox, or in a customer‑controlled environment.

Two orchestration models: Harness‑native sub‑agent delegation and platform fan‑out.

Core Concepts

Brain vs Hands : Brain handles inference, state recovery, and context management; Hands perform file system, shell, and business‑system operations. Hands can run in a managed Cloud Sandbox, a self‑hosted sandbox, or directly on the managed host (Local mode).

Control Plane vs Data Plane : The control plane stores immutable definitions (Agents, Models, Tools, Environments) and governs versioning, ACLs, and lifecycle. The data plane creates Sessions that bind an Agent version to an Environment, maintains the ReAct loop, persists events, and streams updates via SSE.

Environment is an execution‑template (type = local | sandbox | self_hosted) that can be shared across Sessions. Session is a concrete run of an Agent in a specific Environment, holding turn leases, event logs, and a RuntimeContext (userId, sessionId, environment key).

Session Persistence : Sessions are identified by sessionId. After a process restart, the Brain can recover the Agent state from the shared AgentStateStore and continue the conversation.

Tool Result Compaction : Harness enables automatic context compaction and tool‑result eviction. Applications can override thresholds or disable eviction when needed.

File System Abstraction : An AbstractFileSystem decouples logical workspaces from physical backends (local directory, distributed KV store, or E2B sandbox). The same tool definitions work regardless of the underlying storage.

Worker Modes Detailed

Local

All components (Brain, model calls, tool execution) run on the managed cluster. Files and shells are directly accessible in the host namespace. Suitable for development and trusted internal networks.

Cloud Sandbox

Brain remains in the managed cluster, but file and shell operations are executed inside an isolated sandbox (FC Sandbox/E2B compatible). The Brain creates the sandbox, invokes tools via the sandbox API, and the sandbox lifecycle (create, run, recycle) is managed by the platform. Isolation scope is typically per Session.

Self‑hosted

Hands are moved to the customer’s environment. The Brain emits a tool_use event; a customer‑side Worker polls the queue, runs the tool locally or in a private sandbox, and posts the result back as user.tool_result. The Brain never accesses the customer network, and the customer controls sandbox lifecycle, idempotency, and result sanitization.

State Management Layers

Four layers are persisted separately:

Control‑plane resources (Agent definitions, Environments, Skills, Tools) – versioned and ACL‑protected.

Session state – includes turn leases, event log, and RuntimeContext.

AgentStateStore – stores recoverable model context and long‑term memory.

File system / sandbox data – managed via AbstractFileSystem and may be persisted as snapshots or TAR archives.

Recovery requires restoring each layer and re‑linking them via event IDs, tool call IDs, and resource references.

Orchestration Models

Harness native delegation : The orchestrator (e.g., Team Lead) uses sessions_spawn to create Sub‑agents. Parent‑child relationships are explicit, and results are collected via sessions_pending_completions or wait_async_results.

Platform fan‑out : The SaaS API /api/multiagent/run creates independent Managed Sessions for each Agent and streams messages in parallel, suitable for batch analysis or voting.

Summary

AgentScope 2.0 provides a distributed Agent Framework that can be used both for internal data‑agents and as the runtime backbone for Managed Agents offered as a SaaS product. The platform handles resource governance, versioning, and execution boundaries, while Harness supplies a stable inference kernel and pluggable sandbox abstractions, allowing enterprises to adopt Managed Agents without rewriting core inference logic.

Related resources:

AgentScope Builder (GitHub): https://github.com/agentscope-ai/agentscope-java/tree/main/agentscope-examples/agents/agentscope-builder

Documentation: https://java.agentscope.io

AgentScope Java Repository: https://github.com/agentscope-ai/agentscope-java