Skip to content
/
Tier B A9 Sandbox substrate

AgentScope Runtime

agentscope-runtime · agentscope-ai/agentscope-runtime · ★ 800 · last commit 2026-05-21

Primitive shape
No installable primitives
00

Summary

AgentScope Runtime — Summary

AgentScope Runtime is a production-grade Python runtime for AI agent applications that provides three core capabilities: sandboxed tool execution (Python/Shell/GUI/Browser/Filesystem/Mobile), Agent-as-a-Service (AaaS) streaming APIs, and scalable deployment (local, Kubernetes, serverless). The framework exposes agents as FastAPI-based streaming HTTP services (SSE) via the AgentApp base class pattern, which directly inherits from FastAPI for full ecosystem compatibility. It ships a WebUI at webui.runtime.agentscope.io for online testing and supports multiple deployment modes including A2A protocol, Response API, and OpenAI-compatible API.

Status: Archived. As of early 2026, all capabilities have been merged into AgentScope 2.0 at agentscope-ai/agentscope. The repo remains for reference but will be read-only. This analysis covers the final state.

AgentScope Runtime is most similar to claude-flow from the seeds in production-intent and multi-framework compatibility, but differs sharply: it is a Python runtime exposing HTTP/SSE APIs rather than a CLI plugin, its sandbox is a first-class isolation mechanism (not worktrees), and it explicitly targets enterprise AaaS patterns with Kubernetes deployment.

01

Overview

AgentScope Runtime — Overview

Origin

Created by the AgentScope team (agentscope-ai organization) as a production-runtime layer separate from the AgentScope research framework. The project focused on operationalizing agent code into scalable HTTP services. Later merged into AgentScope 2.0.

Philosophy

From the README:

"Core capabilities: Tool Sandboxing — tool call runs inside a hardened sandbox. Agent-as-a-Service (AaaS) APIs — expose agents as streaming, production-ready APIs. Scalable Deployment — deploy locally, on Kubernetes, or serverless for elastic scale."

The framework is "framework-agnostic" in intent — designed to wrap any agent implementation (AgentScope, LangGraph, Microsoft Agent Framework, Agno, AutoGen) with a consistent API surface. The AgentApp class inheriting from FastAPI is the central design decision.

Archive Notice

"With the release of AgentScope 2.0, all capabilities of AgentScope Runtime — including tool sandboxing, Agent-as-a-Service APIs, and full-stack observability — have been natively integrated into AgentScope 2.0. We recommend all users migrate to AgentScope 2.0 for continued updates, new features and community support."

Key Design Decisions

  1. AgentApp directly inherits from FastAPI (v1.1.0 architectural refactor, 2026-02)
  2. Distributed Interrupt Service for manual task preemption during execution
  3. Three sandbox types with async support: BaseSandboxAsync, GuiSandboxAsync, BrowserSandboxAsync
  4. Support for A2A (Agent-to-Agent) protocol
  5. Framework compatibility table (AgentScope: full; LangGraph: messages only; MAF: full; AutoGen: tools only)
02

Architecture

AgentScope Runtime — Architecture

Distribution

  • PyPI: pip install agentscope-runtime
  • Extensions: pip install "agentscope-runtime[ext]"
  • Preview: pip install --pre agentscope-runtime
  • Source: git clone ... && pip install -e .

Directory Structure

src/
  agentscope_runtime/  # Core package
web/
  starter_webui/       # Starter WebUI
cookbook/              # Usage examples
examples/              # Code examples
tests/                 # Test suite

Sandbox Types

Type Description
BaseSandbox / BaseSandboxAsync Base sandbox for Python/Shell execution
GuiSandbox / GuiSandboxAsync GUI automation sandbox
BrowserSandbox / BrowserSandboxAsync Browser automation sandbox
FilesystemSandbox / FilesystemSandboxAsync File operations sandbox
MobileSandbox / MobileSandboxAsync Mobile device sandbox

Required Runtime

  • Python >= 3.10
  • pip or uv package manager
  • Docker (for sandbox isolation)
  • Kubernetes (optional, for scaled deployment)

Deployment Targets

  1. Local (python app.py)
  2. Kubernetes (via DeployManager)
  3. Serverless (elastic auto-scaling)

Install Complexity

pip install agentscope-runtime — one-liner for core. Multi-step for sandbox features (requires Docker).

Target AI Tools

Framework-agnostic. Tested with: AgentScope, LangGraph, Microsoft Agent Framework, Agno, AutoGen.

API Surfaces

  • SSE streaming HTTP endpoint
  • A2A protocol endpoint
  • Response API (OpenAI-compatible)
  • OpenAI SDK in compatible mode
03

Components

AgentScope Runtime — Components

Core Primitives

AgentApp

  • Central class inheriting from FastAPI
  • Three-stage lifecycle: init / query / shutdown
  • SSE streaming support built-in
  • Distributed Interrupt Service for preemption

Sandbox Classes

  • BaseSandbox / BaseSandboxAsync — Python/shell execution sandbox
  • GuiSandboxAsync — GUI automation (non-blocking)
  • BrowserSandboxAsync — Browser control (non-blocking)
  • FilesystemSandboxAsync — File I/O sandbox
  • MobileSandboxAsync — Mobile device interface

DeployManager

  • Handles local and serverless deployment orchestration
  • Exposes agents via configured API surface

Framework Adapters

  • AgentScope adapter (full support: messages + tools)
  • LangGraph adapter (messages only)
  • Microsoft Agent Framework adapter (full: messages + tools)
  • Agno adapter (full: messages + tools)
  • AutoGen adapter (tools only, experimental)

WebUI

  • Starter WebUI at web/starter_webui/
  • Hosted demo: webui.runtime.agentscope.io (online)

API Protocol Support

  • A2A (Agent-to-Agent protocol)
  • Response API
  • OpenAI SDK compatible mode

Scripts / Hooks

None defined at Claude Code hook level. The framework uses FastAPI middleware for lifecycle events.

05

Prompts

AgentScope Runtime — Prompts

Verbatim Excerpt 1: AgentApp Three-Stage Pattern (from README)

from agentscope_runtime import AgentApp

class MyAgent(AgentApp):
    async def init(self):
        # Initialize resources, load models, etc.
        pass

    async def query(self, message: str):
        # Process incoming message and yield streaming responses
        yield {"type": "text", "content": "Hello from agent"}

    async def shutdown(self):
        # Cleanup resources
        pass

Prompting technique: Not a prompt file — this is a runtime contract. The framework separates infrastructure (AgentApp) from agent logic (user-defined). No pre-authored prompts are shipped.

Verbatim Excerpt 2: Sandbox Tool Execution Pattern (from README)

from agentscope_runtime.sandbox import BaseSandboxAsync

sandbox = BaseSandboxAsync()
await sandbox.start()

# Execute Python code in isolated sandbox
result = await sandbox.run_ipython_cell("import math; print(math.sqrt(16))")

# Execute shell command
output = await sandbox.run_shell_command("ls -la /tmp")

await sandbox.stop()

Prompting technique: Imperative code API pattern. No prompt files involved — the "prompting" happens at the agent layer (user-defined), not at the runtime layer.

Observations

AgentScope Runtime ships no pre-authored agent behavior prompts. It is pure infrastructure — sandbox isolation + HTTP serving + deployment. All agent behavior is user-defined on top of the runtime. This is closer to a production runtime platform than a behavioral framework.

09

Uniqueness

AgentScope Runtime — Uniqueness

Differs From Seeds

AgentScope Runtime is closest to claude-flow from the seeds (both target production multi-agent deployments), but differs in kind: AgentScope Runtime is a Python deployment runtime that exposes agents as HTTP/SSE streaming services, while claude-flow is a CLI plugin for Claude Code with SQLite-backed hive-mind coordination. AgentScope Runtime's isolation mechanism is Docker containers for tool execution — the only framework in this batch with a container-first sandbox approach for tool calls specifically. Unlike all seeds, it ships framework-compatibility adapters for LangGraph, MAF, and AutoGen, explicitly positioning itself as a runtime layer above any specific agent framework.

Positioning

An AaaS (Agent-as-a-Service) runtime layer for teams wanting to expose existing agent implementations as production HTTP APIs with containerized tool execution, not a new agent framework.

Observable Failure Modes

  1. Archived: Merged into AgentScope 2.0 — this repo is dead; all users should migrate
  2. Weak framework compatibility: LangGraph adapter only handles messages (not tools); AutoGen adapter is experimental
  3. No pre-built behaviors: Pure infrastructure layer with no behavioral opinions — requires significant user code
  4. Docker dependency: Sandbox isolation requires Docker, adding ops complexity

What Made It Interesting

The clean separation between "agent logic" (AgentApp) and "execution infrastructure" (sandboxes, deployment) was architecturally disciplined. The Distributed Interrupt Service for runtime preemption is not seen in seed frameworks.

04

Workflow

AgentScope Runtime — Workflow

Development Phases

Phase Artifact Description
Implement AgentApp subclass Define init/query/shutdown lifecycle
Sandbox Config Sandbox instance Attach tool execution sandbox
Local Test python app.py + curl/SSE Verify with streaming curl
Deploy DeployManager Push to local or serverless target
Monitor Logs + traces Observe via built-in observability

Key Patterns

# Three-stage AgentApp pattern (v1.1.0+)
class MyAgent(AgentApp):
    async def init(self): ...
    async def query(self, message): ...  # streaming via SSE
    async def shutdown(self): ...

Distributed Interrupt Service

Manual task preemption during execution. Developers customize state persistence and recovery logic flexibly. Added in v1.1.0.

Approval Gates

None automated. Human control via Distributed Interrupt Service (programmatic preemption).

Async Sandbox Execution

All five sandbox types have async variants (*Async) for non-blocking concurrent tool execution. Multiple run_ipython_cell and run_shell_command calls can execute in parallel within one agent turn.

Deployment Gate

DeployManager handles deployment configuration — teams choose local, Kubernetes, or serverless at deploy time.

06

Memory Context

AgentScope Runtime — Memory & Context

State Storage

  • Built-in services for agent state management and conversation history (documented feature)
  • Long-term memory support (documented, implementation details in runtime internals)
  • Sandbox lifecycle control (sandbox state is managed per session)

Memory Type

Unknown at code level — the README promises "state management" as a deployment infrastructure feature but the specific storage backend is not documented in public README/cookbook.

Cross-Session Handoff

Yes — the DeployManager and AgentApp lifecycle (init/query/shutdown) support state persistence across calls. The Distributed Interrupt Service enables custom state persistence and recovery logic.

Compaction

Not documented. Not handled by the runtime — delegated to the user's AgentApp implementation.

Observability

Full-stack observability: logs + traces. Specific tools not named in README (likely standard Python logging + optional OTel integration).

WebUI

Hosted demo at webui.runtime.agentscope.io for testing — not a local dashboard. Starter WebUI template at web/starter_webui/.

State Files

None specified (managed by DeployManager internals).

07

Orchestration

AgentScope Runtime — Orchestration

Multi-Agent Support

Yes — the framework supports multi-agent collaboration with enhanced capabilities (mentioned in v1.0 release).

Orchestration Pattern

Not prescriptive — the runtime provides HTTP/SSE API surface; orchestration pattern depends on user's AgentApp implementation. The framework itself does not impose sequential vs. parallel.

Isolation Mechanism

Container — sandboxed tool execution runs in Docker containers (hardened sandbox). This is the key isolation primitive: tool calls execute inside isolated containers, not on the host.

Subagent Definition Format

Not applicable in the skill-pack sense — agents are defined as AgentApp subclasses (code-class). Multi-agent collaboration is via A2A protocol calls between AgentApp instances.

Multi-Model Usage

Unknown — the framework is model-agnostic (framework-agnostic runtime). Users supply their own model client.

Execution Mode

Event-driven — HTTP request triggers query execution; SSE streams response.

Consensus Mechanism

None documented.

Prompt Chaining

Yes — agents can call other agents via A2A protocol, creating prompt chains.

Crash Recovery

Yes — Distributed Interrupt Service provides custom state persistence and recovery logic.

Context Compaction

Not handled — user-defined.

Cross-Session Handoff

Yes — conversation history managed by deployment infrastructure.

Streaming Output

Yes — SSE streaming is the primary response mechanism.

08

Ui Cli Surface

AgentScope Runtime — UI / CLI Surface

CLI Binary

None shipped. Framework is a Python library — agents are run as standard Python scripts or via uvicorn/gunicorn.

Local Web UI

  • Starter WebUI template at web/starter_webui/ (local, user-deployed)
  • Hosted demo at webui.runtime.agentscope.io (online, read-only test environment)
  • Not a configurable local dashboard — requires user deployment of the WebUI template

Observability

  • Full-stack logs and traces (built-in)
  • Specific OTel integration not confirmed in public README

API Access

  • SSE streaming endpoint (primary)
  • A2A protocol endpoint
  • Response API (REST)
  • OpenAI-compatible API endpoint

IDE Integration

None. Pure Python library.

Cross-Tool Portability

High — framework-agnostic runtime works with any Python agent framework (AgentScope, LangGraph, MAF, Agno, AutoGen). Not tied to any IDE or AI client.

Related frameworks

same archetype · same primary tool · same memory type

Daytona ★ 72k
A9 Sandbox substrate

Provide secure, elastic, sub-90ms sandbox compute infrastructure for running AI-generated code, accessible via multi-language…

CUA ★ 17k
A9 Sandbox substrate

Unified SDK for building, benchmarking, and deploying agents that interact with full OS GUIs via isolated VMs.

E2B ★ 12k
A9 Sandbox substrate

Run AI-generated code safely in cloud-hosted isolated sandboxes via a 3-line SDK integration.

OpenSandbox ★ 11k
A9 Sandbox substrate

Protocol-first general-purpose sandbox platform for AI applications with multi-language SDKs and pluggable isolation backends.

Microsandbox ★ 6.3k
A9 Sandbox substrate

Spawn hardware-isolated microVMs as child processes directly from application code, with no server setup, in under 100ms.

CubeSandbox ★ 5.9k
A9 Sandbox substrate

Sub-60ms KVM microVM sandboxes for AI agents with E2B drop-in compatibility and <5MB memory overhead.