[Cookbook] [δΈζREADME] [Samples]
A Production-Ready Runtime Framework for Intelligent Agent Applications
AgentScope Runtime is a full-stack agent runtime that tackles two core challenges: efficient agent deployment and secure sandbox execution. It ships with foundational services such as short- and long-term memory plus agent state persistence, along with hardened sandbox infrastructure. Whether you need to orchestrate production-grade agents or guarantee safe tool interactions, AgentScope Runtime provides developer-friendly workflows with complete observability.
In V1.0, these services are exposed via an adapter pattern, enabling seamless integration with the native modules of different agent frameworks while preserving their native interfaces and behaviors, ensuring both compatibility and flexibility.
- [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.
- ποΈ 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
AgentAppfor 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 | Service |
|---|---|---|---|
| AgentScope | β | β | β |
| LangGraph | β | π§ | π§ |
| AutoGen | π§ | β | π§ |
| Microsoft Agent Framework | π§ | π§ | π§ |
| Agno | β | β | π§ |
Welcome to join our community on
| Discord | DingTalk |
|---|---|
- Python 3.10 or higher
- pip or uv package manager
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 .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:
@agent_app.initβ Initialize services/resources at startup@agent_app.query(framework="agentscope")β Core logic for handling requests, must usestream_printing_messagestoyield msg, lastfor streaming output@agent_app.shutdownβ Clean up services/resources on exit
import os
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_runtime.engine import AgentApp
from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest
from agentscope_runtime.adapters.agentscope.memory import (
AgentScopeSessionHistoryMemory,
)
from agentscope_runtime.engine.services.agent_state import (
InMemoryStateService,
)
from agentscope_runtime.engine.services.session_history import (
InMemorySessionHistoryService,
)
agent_app = AgentApp(
app_name="Friday",
app_description="A helpful assistant",
)
@agent_app.init
async def init_func(self):
self.state_service = InMemoryStateService()
self.session_service = InMemorySessionHistoryService()
await self.state_service.start()
await self.session_service.start()
@agent_app.shutdown
async def shutdown_func(self):
await self.state_service.stop()
await self.session_service.stop()
@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
state = await self.state_service.export_state(
session_id=session_id,
user_id=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=AgentScopeSessionHistoryMemory(
service=self.session_service,
session_id=session_id,
user_id=user_id,
),
formatter=DashScopeChatFormatter(),
)
agent.set_console_output_enabled(enabled=False)
if state:
agent.load_state_dict(state)
async for msg, last in stream_printing_messages(
agents=[agent],
coroutine_task=agent(msgs),
):
yield msg, last
state = agent.state_dict()
await self.state_service.save_state(
user_id=user_id,
session_id=session_id,
state=state,
)
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", ... }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
Current version requires Docker or Kubernetes to be installed and running on your system. Please refer to this tutorial for more details.
If you plan to use the sandbox on a large scale in production, we recommend deploying it directly in Alibaba Cloud for managed hosting: One-click deploy sandbox on Alibaba Cloud
Use for running Python code or shell commands in an isolated environment.
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...")Provides a virtual desktop environment for mouse, keyboard, and screen operations.
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...")A GUI-based sandbox with browser operations inside an isolated sandbox.
from agentscope_runtime.sandbox import BrowserSandbox
with BrowserSandbox() as box:
# By default, pulls `agentscope/runtime-sandbox-browser:latest` from DockerHub
print(box.list_tools()) # List all available tools
print(box.desktop_url) # Web desktop access URL
box.browser_navigate("https://www.google.com/") # Open a webpage
input("Press Enter to continue...")A GUI-based sandbox with file system operations such as creating, reading, and deleting files.
from agentscope_runtime.sandbox import FilesystemSandbox
with FilesystemSandbox() as box:
# By default, pulls `agentscope/runtime-sandbox-filesystem:latest` from DockerHub
print(box.list_tools()) # List all available tools
print(box.desktop_url) # Web desktop access URL
box.create_directory("test") # Create a directory
input("Press Enter to continue...")Provides a sandboxed Android emulator environment that allows executing various mobile operations, such as tapping, swiping, inputting text, and taking screenshots.
-
Linux Host: When running on a Linux host, this sandbox requires the
binderandashmemkernel modules to be loaded. If they are missing, execute the following commands on your host to install and load the required modules:# 1. Install extra kernel modules sudo apt update && sudo apt install -y linux-modules-extra-`uname -r` # 2. Load modules and create device nodes sudo modprobe binder_linux devices="binder,hwbinder,vndbinder" sudo modprobe ashmem_linux
-
Architecture Compatibility: When running on an ARM64/aarch64 architecture (e.g., Apple M-series chips), you may encounter compatibility or performance issues. It is recommended to run on an x86_64 host.
from agentscope_runtime.sandbox import MobileSandbox
with MobileSandbox() as box:
# By default, pulls 'agentscope/runtime-sandbox-mobile:latest' from DockerHub
print(box.list_tools()) # List all available tools
print(box.mobile_get_screen_resolution()) # Get the screen resolution
print(box.mobile_tap([500, 1000])) # Tap at coordinate (500, 1000)
print(box.mobile_input_text("Hello from AgentScope!")) # Input text
print(box.mobile_key_event(3)) # Sends a HOME key event (KeyCode: 3)
screenshot_result = box.mobile_get_screenshot() # Get the current screenshot
input("Press Enter to continue...")Note
To add tools to the AgentScope Toolkit:
-
Wrap sandbox tool with
sandbox_tool_adapter, so the AgentScope agent can call them:from agentscope_runtime.adapters.agentscope.tool import sandbox_tool_adapter wrapped_tool = sandbox_tool_adapter(sandbox.browser_navigate)
-
Register the tool with
register_tool_function:toolkit = Toolkit() Toolkit.register_tool_function(wrapped_tool)
If pulling images from DockerHub fails (for example, due to network restrictions), you can switch the image source to Alibaba Cloud Container Registry for faster access:
export RUNTIME_SANDBOX_REGISTRY="agentscope-registry.ap-southeast-1.cr.aliyuncs.com"A namespace is used to distinguish images of different teams or projects. You can customize the namespace via an environment variable:
export RUNTIME_SANDBOX_IMAGE_NAMESPACE="agentscope"For example, here agentscope will be used as part of the image path.
An image tag specifies the version of the image, for example:
export RUNTIME_SANDBOX_IMAGE_TAG="preview"Details:
- Default is
latest, which means the image version matches the PyPI latest release. previewmeans the latest preview version built in sync with the GitHub main branch.- You can also use a specified version number such as
20250909. You can check all available image versions at DockerHub.
The sandbox SDK will build the full image path based on the above environment variables:
<RUNTIME_SANDBOX_REGISTRY>/<RUNTIME_SANDBOX_IMAGE_NAMESPACE>/runtime-sandbox-base:<RUNTIME_SANDBOX_IMAGE_TAG>Example:
agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:previewAgentScope Runtime also supports serverless deployment, which is suitable for running sandboxes in a serverless environment, Alibaba Cloud Function Compute (FC) or Alibaba Cloud AgentRun.
First, please refer to the documentation to configure the serverless environment variables.
Make CONTAINER_DEPLOYMENT to fc or agentrun to enable serverless deployment.
Then, start a sandbox server, use the --config option to specify a serverless environment setup:
# This command will load the settings defined in the `custom.env` file
runtime-sandbox-server --config fc.envAfter the server starts, you can access the sandbox server at baseurl http://localhost:8000 and invoke sandbox tools described above.
- π Cookbook: Comprehensive tutorials
- π‘ Concept: Core concepts and architecture overview
- π Quick Start: Quick start tutorial
- π Demo House: Rich example projects
- π API Reference: Complete API documentation
The AgentApp exposes a deploy method that takes a DeployManager instance and deploys the agent.
-
The service port is set as the parameter
portwhen creating theLocalDeployManager. -
The service endpoint path is set as the parameter
endpoint_pathto/processwhen deploying the agent. -
The deployer will automatically add common agent protocols, such as A2A, Response API.
After deployment, users can access the service at `http://localhost:8090/process:
from agentscope_runtime.engine.deployers import LocalDeployManager
# Create deployment manager
deployer = LocalDeployManager(
host="0.0.0.0",
port=8090,
)
# Deploy the app as a streaming service
deploy_result = await app.deploy(deployer=deployer)After deployment, users can also access this service using the Response API of the OpenAI SDK:
from openai import OpenAI
client = OpenAI(base_url="http://0.0.0.0:8090/compatible-mode/v1")
response = client.responses.create(
model="any_name",
input="What is the weather in Beijing?"
)
print(response)Besides, DeployManager also supports serverless deployments, such as deploying your agent app
to ModelStudio
or AgentRun.
from agentscope_runtime.engine.deployers import ModelStudioDeployManager
# Create deployment manager
deployer = ModelstudioDeployManager(
oss_config=OSSConfig(
access_key_id=os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID"),
access_key_secret=os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
),
modelstudio_config=ModelstudioConfig(
workspace_id=os.environ.get("MODELSTUDIO_WORKSPACE_ID"),
access_key_id=os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID"),
access_key_secret=os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
dashscope_api_key=os.environ.get("DASHSCOPE_API_KEY"),
),
)
# Deploy to ModelStudio
result = await app.deploy(
deployer,
deploy_name="agent-app-example",
telemetry_enabled=True,
requirements=["agentscope", "fastapi", "uvicorn"],
environment={
"PYTHONPATH": "/app",
"DASHSCOPE_API_KEY": os.environ.get("DASHSCOPE_API_KEY"),
},
)For more advanced serverless deployment guides, please refer to the documentation.
We welcome contributions from the community! Here's how you can help:
- Use GitHub Issues to report bugs
- Include detailed reproduction steps
- Provide system information and logs
- Discuss new ideas in GitHub Discussions
- Follow the feature request template
- Consider implementation feasibility
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
For detailed contributing guidelines, please see CONTRIBUTE.
AgentScope Runtime is released under the Apache License 2.0.
Copyright 2025 Tongyi Lab
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!