[Cookbook] [δΈζREADME] [Samples]
A Production-Ready Runtime Framework for Intelligent Agent Applications
AgentScope Runtime tackles two critical challenges in agent development: secure sandboxed tool execution and scalable agent deployment. Built with a dual-core architecture, it provides framework-agnostic infrastructure for deploying agents with full observability and safe tool interactions.
- [2025-10] We released
v0.2.0β introducingAgentAppAPI server support, enabling easy use of agent applications and custom API endpoints through synchronous, asynchronous, and streaming interfaces. Check our cookbook for more details. - [2025-10] GUI Sandbox is added with support for virtual desktop environments, mouse, keyboard, and screen operations. Introduced the
desktop_urlproperty for GUI Sandbox, Browser Sandbox, and Filesystem Sandbox β allowing direct access to the virtual desktop via your browser. Check our cookbook for more details.
-
ποΈ Deployment Infrastructure: Built-in services for session management, memory, and sandbox environment control
-
π Sandboxed Tool Execution: Isolated sandboxes ensure safe tool execution without system compromise
-
π§ Framework Agnostic: Not tied to any specific framework. Works seamlessly with popular open-source agent frameworks and custom implementations
-
β‘ Developer Friendly: Simple deployment with powerful customization options
-
π Observability: Comprehensive tracing and monitoring for runtime operations
Welcome to join our community on
| Discord | DingTalk |
|---|---|
![]() |
![]() |
- π Quick Start
- π Cookbook
- π Agent Framework Integration
- ποΈ Deployment
- π€ Contributing
- π License
- Python 3.10 or higher
- pip or uv package manager
From PyPI:
# Install core dependencies
pip install 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. The server will process your input and return streaming agent-generated responses.
import os
from agentscope_runtime.engine import AgentApp
from agentscope_runtime.engine.agents.agentscope_agent import AgentScopeAgent
from agentscope.agent import ReActAgent
from agentscope.model import OpenAIChatModel
agent = AgentScopeAgent(
name="Friday",
model=OpenAIChatModel(
"gpt-4",
api_key=os.getenv("OPENAI_API_KEY"),
),
agent_config={
"sys_prompt": "You're a helpful assistant named Friday.",
},
agent_builder=ReActAgent, # Or use your own agent builder
)
app = AgentApp(agent=agent, endpoint_path="/process")
app.run(host="0.0.0.0", 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":"content","status":"in_progress","text":"The" }
data: {"sequence_number":3,"object":"content","status":"in_progress","text":" capital of France is Paris." }
data: {"sequence_number":4,"object":"message","status":"completed","text":"The capital of France is Paris." }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...")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:preview- π Cookbook: Comprehensive tutorials
- π‘ Concept: Core concepts and architecture overview
- π Quick Start: Quick start tutorial
- π Demo House: Rich example projects
- π API Reference: Complete API documentation
# pip install "agentscope-runtime[agno]"
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agentscope_runtime.engine.agents.agno_agent import AgnoAgent
agent = AgnoAgent(
name="Friday",
model=OpenAIChat(
id="gpt-4",
),
agent_config={
"instructions": "You're a helpful assistant.",
},
agent_builder=Agent,
)# pip install "agentscope-runtime[autogen]"
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from agentscope_runtime.engine.agents.autogen_agent import AutogenAgent
agent = AutogenAgent(
name="Friday",
model=OpenAIChatCompletionClient(
model="gpt-4",
),
agent_config={
"system_message": "You're a helpful assistant",
},
agent_builder=AssistantAgent,
)# pip install "agentscope-runtime[langgraph]"
from typing import TypedDict
from langgraph import graph, types
from agentscope_runtime.engine.agents.langgraph_agent import LangGraphAgent
# define the state
class State(TypedDict, total=False):
id: str
# define the node functions
async def set_id(state: State):
new_id = state.get("id")
assert new_id is not None, "must set ID"
return types.Command(update=State(id=new_id), goto="REVERSE_ID")
async def reverse_id(state: State):
new_id = state.get("id")
assert new_id is not None, "ID must be set before reversing"
return types.Command(update=State(id=new_id[::-1]))
state_graph = graph.StateGraph(state_schema=State)
state_graph.add_node("SET_ID", set_id)
state_graph.add_node("REVERSE_ID", reverse_id)
state_graph.set_entry_point("SET_ID")
compiled_graph = state_graph.compile(name="ID Reversal")
agent = LangGraphAgent(graph=compiled_graph)Note
More agent framework interations are comming soon!
The app exposes a deploy method that takes a DeployManager instance and deploys the agent.
The service port is set as the parameter port when creating the LocalDeployManager.
The service endpoint path is set as the parameter endpoint_path when deploying the agent.
The deployer will automatically add common agent protocols, such as A2A, Response API based on the default endpoint /process.
In this example, we set the endpoint path to /process,
after deployment, users can access the service at http://localhost:8090/process, and can also access the service from OpenAI SDK by Response API.
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)Then user could query the deployment by 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)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!




