Agentscope Runtime

> [!IMPORTANT] > ## 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 (https://github.com/agentscope-ai/agentscope) for continued updates, new features and community support. This repository will remain available in read-only mode for reference and will be archived soon. > > Thank you to everyone who contributed to and used AgentScope Runtime!

AgentScope Runtime: A Production-grade Runtime for Agent Applications

[](https://github.com/agentscope-ai/agentscope-runtime) [](http://webui.runtime.agentscope.io/) [](https://pypi.org/project/agentscope-runtime/) [](https://pepy.tech/project/agentscope-runtime) [](https://python.org) [](https://github.com/agentscope-ai/agentscope-runtime) [](LICENSE) [](https://github.com/psf/black) [](https://github.com/agentscope-ai/agentscope-runtime/stargazers) [](https://github.com/agentscope-ai/agentscope-runtime/network) [](https://github.com/agentscope-ai/agentscope-runtime/actions) [](https://runtime.agentscope.io) [](https://deepwiki.com/agentscope-ai/agentscope-runtime) [](https://a2a-protocol.org/) [](https://modelcontextprotocol.io/) [](https://discord.gg/eYMpfnkG8h) [](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&dtno_comment=1&origin=11)

[[Cookbook]](https://runtime.agentscope.io/) [[Try WebUI]](http://webui.runtime.agentscope.io/) [[中文README]](README_zh.md) [[Samples]](https://github.com/agentscope-ai/agentscope-samples)

> 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 > > > Plus > > > > Full-stack observability (logs / traces) > > Framework compatibility with mainstream agent frameworks > >

---

Table of Contents

> [!NOTE] > > Recommended reading order: > > - I want to run an agent app in 5 minutes: Quick Start (Agent App example) → verify with curl (SSE streaming) > - I care about secure tool execution / automation: Quick Start (Sandbox examples) → sandbox image registry/namespace/tag configuration → (optional) production-grade serverless sandbox deployment > - I want production deployment / expose APIs: Quick Start (Agent App example) → Quick Start (Deployment example) → Guides > - I want to contribute: Contributing → Contact

• [News](#-news)
• [Key Features](#-key-features)
• [Quick Start](#-quick-start): From installation to running a minimal Agent API service. Learn the three-stage AgentApp development pattern: init / query / shutdown.
• [Prerequisites](#prerequisites): Required runtime environment and dependencies
• [Installation](#installation): Install from PyPI or from source
• [Agent App Example](#agent-app-example): How to build a streaming (SSE) Agent-as-a-Service API
• [Sandbox Example](#sandbox-example): How to safely execute Python/Shell/GUI/Browser/Filesystem/Mobile tools in an isolated sandbox
• [Deployment Example](#deployment-example): Learn to deploy with DeployManager locally or in a serverless environment, and access the service via A2A, Response API, or the OpenAI SDK in compatible mode
• [Guides](#-guides): A tutorial site covering AgentScope Runtime concepts, architecture, APIs, and sample projects—helping you move from “it runs” to “scalable and maintainable”.
• [Contact](#-contact)
• [Contributing](#-contributing)
• [License](#-license)
• [Contributors](#-contributors)

---

🆕 NEWS

• [2026-02] A major architectural refactor of AgentApp in v1.1.0. By adopting direct inheritance from FastAPI and deprecating the previous factory pattern, AgentApp now offers seamless integration with the full FastAPI ecosystem, significantly boosting extensibility. Furthermore, we've introduced a Distributed Interrupt Service, enabling manual task preemption during agent execution and allowing developers to customize state persistence and recovery logic flexibly. Please refer to the CHANGELOG for full update details and migration guide.
• [2026-01] Added asynchronous sandbox implementations (BaseSandboxAsync, GuiSandboxAsync, BrowserSandboxAsync, FilesystemSandboxAsync, MobileSandboxAsync) enabling non-blocking, concurrent tool execution in async program. Improved run_ipython_cell and run_shell_command methods with enhanced concurrency and parallel execution capabilities for more efficient sandbox operations.
• [2025-12] We have released AgentScope Runtime v1.0, introducing a unified “Agent as API” white-box development experience, with enhanced multi-agent collaboration, state persistence, and cross-framework integration. This release also streamlines abstractions and modules to ensure consistency between development and production environments. Please refer to the CHANGELOG for full update details and migration guide.

---

✨ Key Features

• Deployment Infrastructure: Built-in services for agent state management, conversation history, long-term memory, and sandbox lifecycle control
• Framework-Agnostic: Not tied to any specific agent framework; seamlessly integrates with popular open-source and custom implementations
• Developer-Friendly: Offers AgentApp for easy deployment with powerful customization options
• Observability: Comprehensive tracking and monitoring of runtime operations
• Sandboxed Tool Execution: Isolated sandbox ensures safe tool execution without affecting the system
• Out-of-the-Box Tools & One-Click Adaptation: Rich set of ready-to-use tools, with adapters enabling quick integration into different frameworks

> [!NOTE] > > About Framework-Agnostic: Currently, AgentScope Runtime supports the AgentScope framework. We plan to extend compatibility to more agent development frameworks in the future. This table shows the current version’s adapter support for different frameworks. The level of support for each functionality varies across frameworks: > > | Framework/Feature | Message/Event | Tool | > | ------------------------------------------------------------ | ------------- | ---- | > | AgentScope | ✅ | ✅ | > | LangGraph | ✅ | 🚧 | > | Microsoft Agent Framework | ✅ | ✅ | > | Agno | ✅ | ✅ | > | AutoGen | 🚧 | ✅ |

---

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• pip or uv package manager

Installation

From PyPI:

# Install core dependencies
pip install agentscope-runtime

# Install extension
pip install "agentscope-runtime[ext]"

# Install preview version
pip install --pre agentscope-runtime

(Optional) From source:

# Pull the source code from GitHub
git clone -b main https://github.com/agentscope-ai/agentscope-runtime.git
cd agentscope-runtime

# Install core dependencies
pip install -e .

Agent App Example

This example demonstrates how to create an agent API server using agentscope ReActAgent and AgentApp. To run a minimal AgentScope Agent with AgentScope Runtime, you generally need to implement:

1. Define lifespan – Use contextlib.asynccontextmanager to manage resource initialization (e.g., state services) at startup and cleanup on exit.
2. @agent_app.query(framework="agentscope") – Core logic for handling requests, must use stream_printing_messages to yield msg, last for streaming output

import os
from contextlib import asynccontextmanager

from fastapi import FastAPI
from agentscope.agent import ReActAgent
from agentscope.model import DashScopeChatModel
from agentscope.formatter import DashScopeChatFormatter
from agentscope.tool import Toolkit, execute_python_code
from agentscope.pipeline import stream_printing_messages
from agentscope.memory import InMemoryMemory
from agentscope.session import RedisSession

from agentscope_runtime.engine import AgentApp
from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest

# 1. Define lifespan manager
@asynccontextmanager
async def lifespan(app: FastAPI):
    """Manage resources during service startup and shutdown"""
    # Startup: Initialize Session manager
    import fakeredis

    fake_redis = fakeredis.aioredis.FakeRedis(decode_responses=True)
    # NOTE: This FakeRedis instance is for development/testing only.
    # In production, replace it with your own Redis client/connection
    # (e.g., aioredis.Redis)
    app.state.session = RedisSession(connection_pool=fake_redis.connection_pool)

    yield  # Service is running

    # Shutdown: Add cleanup logic here (e.g., closing database connections)
    print("AgentApp is shutting down...")

# 2. Create AgentApp instance
agent_app = AgentApp(
    app_name="Friday",
    app_description="A helpful assistant",
    lifespan=lifespan,
)

# 3. Define request handling logic
@agent_app.query(framework="agentscope")
async def query_func(
    self,
    msgs,
    request: AgentRequest = None,
    **kwargs,
):
    session_id = request.session_id
    user_id = request.user_id

    toolkit = Toolkit()
    toolkit.register_tool_function(execute_python_code)

    agent = ReActAgent(
        name="Friday",
        model=DashScopeChatModel(
            "qwen-turbo",
            api_key=os.getenv("DASHSCOPE_API_KEY"),
            stream=True,
        ),
        sys_prompt="You're a helpful assistant named Friday.",
        toolkit=toolkit,
        memory=InMemoryMemory(),
        formatter=DashScopeChatFormatter(),
    )
    agent.set_console_output_enabled(enabled=False)

    # Load state
    await agent_app.state.session.load_session_state(
        session_id=session_id,
        user_id=user_id,
        agent=agent,
    )

    async for msg, last in stream_printing_messages(
        agents=[agent],
        coroutine_task=agent(msgs),
    ):
        yield msg, last

    # Save state
    await agent_app.state.session.save_session_state(
        session_id=session_id,
        user_id=user_id,
        agent=agent,
    )

# 4. Run the application
agent_app.run(host="127.0.0.1", port=8090)

The server will start and listen on: http://localhost:8090/process. You can send JSON input to the API using curl:

curl -N \
  -X POST "http://localhost:8090/process" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What is the capital of France?" }
        ]
      }
    ]
  }'

You’ll see output streamed in Server-Sent Events (SSE) format:

data: {"sequence_number":0,"object":"response","status":"created", ... }
data: {"sequence_number":1,"object":"response","status":"in_progress", ... }
data: {"sequence_number":2,"object":"message","status":"in_progress", ... }
data: {"sequence_number":3,"object":"content","status":"in_progress","text":"The" }
data: {"sequence_number":4,"object":"content","status":"in_progress","text":" capital of France is Paris." }
data: {"sequence_number":5,"object":"message","status":"completed","text":"The capital of France is Paris." }
data: {"sequence_number":6,"object":"response","status":"completed", ... }

Sandbox Example

These examples demonstrate how to create sandboxed environments and execute tools within them, with some examples featuring interactive frontend interfaces accessible via VNC (Virtual Network Computing):

> [!NOTE] > > If you want to run the sandbox locally, the current version supports Docker (optionally with gVisor) or BoxLite as the backend, and you can switch the backend by setting the environment variable CONTAINER_DEPLOYMENT (supported values include docker / gvisor / boxlite etc.; default: docker). > > For large-scale remote/production deployments, we recommend using Kubernetes (K8s), Function Compute (FC), or Alibaba Cloud Container Service for Kubernetes (ACK) as the backend. Please refer to this tutorial for more details.

> [!TIP] > AgentScope Runtime provides both synchronous and asynchronous versions for each sandbox type

| Synchronous Class | Asynchronous Class | | ------------------- | ------------------------ | | BaseSandbox | BaseSandboxAsync | | GuiSandbox | GuiSandboxAsync | | FilesystemSandbox | FilesystemSandboxAsync | | BrowserSandbox | BrowserSandboxAsync | | MobileSandbox | MobileSandboxAsync | | TrainingSandbox | - | | AgentbaySandbox | - |

Base Sandbox

Use for running Python code or shell commands in an isolated environment.

# --- Synchronous version ---
from agentscope_runtime.sandbox import BaseSandbox

with BaseSandbox() as box:
    # By default, pulls `agentscope/runtime-sandbox-base:latest` from DockerHub
    print(box.list_tools()) # List all available tools
    print(box.run_ipython_cell(code="print('hi')"))  # Run Python code
    print(box.run_shell_command(command="echo hello"))  # Run shell command
    input("Press Enter to continue...")

# --- Asynchronous version ---
from agentscope_runtime.sandbox import BaseSandboxAsync

async with BaseSandboxAsync() as box:
    # Default image is `agentscope/runtime-sandbox-base:latest`
    print(await box.list_tools_async())  # List all available tools
    print(await box.run_ipython_cell(code="print('hi')"))  # Run Python code
    print(await box.run_shell_command(command="echo hello"))  # Run shell command
    input("Press Enter to continue...")

GUI Sandbox

Provides a virtual desktop environment for mouse, keyboard, and screen operations.

# --- Synchronous version ---
from agentscope_runtime.sandbox import GuiSandbox

with GuiSandbox() as box:
    # By default, pulls `agentscope/runtime-sandbox-gui:latest` from DockerHub
    print(box.list_tools())  # List all available tools
    print(box.desktop_url)  # Web desktop access URL
    print(box.computer_use(action="get_cursor_position"))  # Get mouse cursor position
    print(box.computer_use(action="get_screenshot"))  # Capture screenshot
    input("Press Enter to continue...")

# --- Asynchronous version ---
from agentscope_runtime.sandbox import GuiSandboxAsync

async with GuiSandboxAsync() as box:
    # Default image is `agentscope/runtime-sandbox-gui:latest`
    print(await box.list_tools_async())  # List all available tools
    print(box.desktop_url)  # Web desktop access URL
    print(await box.computer_use(action="get_cursor_position"))  # Get mouse cursor position
    print(await box.computer_use(action="get_screenshot"))  # Capture screenshot
    input("Press Enter to continue...")

Browser Sandbox

A GUI-based sandbox with browser operations inside an isolated sandbox.

# --- Synchronous version ---
from agentscope_runtime.sandbox import BrowserSandbox

with BrowserSandbox() as box:
    # By default, pulls `agentscope/runtime-sandbox-br

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agentscope-ai](https://github.com/agentscope-ai)
- **Source:** [agentscope-ai/agentscope-runtime](https://github.com/agentscope-ai/agentscope-runtime)
- **License:** Apache-2.0
- **Homepage:** https://runtime.agentscope.io/

Install and usage instructions live in the source repository linked above.