Content
<div align="center">
# AgentScope Runtime
[](https://pypi.org/project/agentscope-runtime/)
[](https://pepy.tech/project/agentscope-runtime)
[](https://python.org)
[](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=&_dt_no_comment=1&origin=11)
[[Cookbook]](https://runtime.agentscope.io/)
[[中文README]](README_zh.md)
[[Samples]](https://github.com/agentscope-ai/agentscope-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.*
</div>
---
## 🆕 NEWS
* **[2025-10]** **GUI Sandbox** is added with support for virtual desktop environments, mouse, keyboard, and screen operations. Introduced the **`desktop_url`** property for GUI Sandbox, Browser Sandbox, and Filesystem Sandbox — allowing direct access to the virtual desktop via your browser. Check our [cookbook](https://runtime.agentscope.io/en/sandbox.html#sandbox-usage) for more details.
---
## ✨ Key Features
- **🏗️ 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
---
## 💬 Contact
Welcome to join our community on
| [Discord](https://discord.gg/eYMpfnkG8h) | DingTalk |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| <img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="100" height="100"> | <img src="https://img.alicdn.com/imgextra/i1/O1CN01LxzZha1thpIN2cc2E_!!6000000005934-2-tps-497-477.png" width="100" height="100"> |
---
## 📋 Table of Contents
- [🚀 Quick Start](#-quick-start)
- [📚 Cookbook](#-cookbook)
- [🔌 Agent Framework Integration](#-agent-framework-integration)
- [🏗️ Deployment](#️-deployment)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
---
## 🚀 Quick Start
### Prerequisites
- Python 3.10 or higher
- pip or uv package manager
### Installation
From PyPI:
```bash
# Install core dependencies
pip install agentscope-runtime
```
(Optional) From source:
```bash
# 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 .
```
### Basic Agent Usage Example
This example demonstrates how to create an agentscope agent using AgentScope Runtime and
stream responses from the Qwen model.
```python
import asyncio
import os
from agentscope_runtime.engine import Runner
from agentscope_runtime.engine.agents.agentscope_agent import AgentScopeAgent
from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest
from agentscope_runtime.engine.services.context_manager import ContextManager
from agentscope.agent import ReActAgent
from agentscope.model import OpenAIChatModel
async def main():
# Set up the language model and agent
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,
)
async with ContextManager() as context_manager:
runner = Runner(agent=agent, context_manager=context_manager)
# Create a request and stream the response
request = AgentRequest(
input=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is the capital of France?",
},
],
},
],
)
async for message in runner.stream_query(request=request):
if hasattr(message, "text"):
print(f"Streamed Answer: {message.text}")
asyncio.run(main())
```
### Basic Sandbox Usage 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]
>
> Current version requires Docker or Kubernetes to be installed and running on your system. Please refer to [this tutorial](https://runtime.agentscope.io/en/sandbox.html) 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](https://computenest.console.aliyun.com/service/instance/create/default?ServiceName=AgentScope%20Runtime%20%E6%B2%99%E7%AE%B1%E7%8E%AF%E5%A2%83)
#### Base Sandbox
Use for running **Python code** or **shell commands** in an isolated environment.
```python
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...")
```
#### GUI Sandbox
Provides a **virtual desktop** environment for mouse, keyboard, and screen operations.
<img src="https://img.alicdn.com/imgextra/i2/O1CN01df5SaM1xKFQP4KGBW_!!6000000006424-2-tps-2958-1802.png" alt="GUI Sandbox" width="800" height="500">
```python
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...")
```
#### Browser Sandbox
A GUI-based sandbox with **browser operations** inside an isolated sandbox.
<img src="https://img.alicdn.com/imgextra/i4/O1CN01OIq1dD1gAJMcm0RFR_!!6000000004101-2-tps-2734-1684.png" alt="GUI Sandbox" width="800" height="500">
```python
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...")
```
#### Filesystem Sandbox
A GUI-based sandbox with **file system operations** such as creating, reading, and deleting files.
<img src="https://img.alicdn.com/imgextra/i3/O1CN01VocM961vK85gWbJIy_!!6000000006153-2-tps-2730-1686.png" alt="GUI Sandbox" width="800" height="500">
```python
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...")
```
#### Configuring Sandbox Image Registry, Namespace, and Tag
##### 1. Registry
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:
```bash
export RUNTIME_SANDBOX_REGISTRY="agentscope-registry.ap-southeast-1.cr.aliyuncs.com"
```
##### 2. Namespace
A namespace is used to distinguish images of different teams or projects. You can customize the namespace via an environment variable:
```bash
export RUNTIME_SANDBOX_IMAGE_NAMESPACE="agentscope"
```
For example, here `agentscope` will be used as part of the image path.
##### 3. Tag
An image tag specifies the version of the image, for example:
```bash
export RUNTIME_SANDBOX_IMAGE_TAG="preview"
```
Details:
- Default is `latest`, which means the image version matches the PyPI latest release.
- `preview` means 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](https://hub.docker.com/repositories/agentscope).
##### 4. Complete Image Path
The sandbox SDK will build the full image path based on the above environment variables:
```bash
<RUNTIME_SANDBOX_REGISTRY>/<RUNTIME_SANDBOX_IMAGE_NAMESPACE>/runtime-sandbox-base:<RUNTIME_SANDBOX_IMAGE_TAG>
```
Example:
```bash
agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:preview
```
---
## 📚 Cookbook
- **[📖 Cookbook](https://runtime.agentscope.io/en/intro.html)**: Comprehensive tutorials
- **[💡 Concept](https://runtime.agentscope.io/en/concept.html)**: Core concepts and architecture overview
- **[🚀 Quick Start](https://runtime.agentscope.io/en/quickstart.html)**: Quick start tutorial
- **[🏠 Demo House](https://runtime.agentscope.io/en/demohouse.html)**: Rich example projects
- **[📋 API Reference](https://runtime.agentscope.io/en/api/index.html)**: Complete API documentation
---
## 🔌 Agent Framework Integration
### Agno Integration
```python
# 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,
)
```
### AutoGen Integration
```python
# 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,
)
```
### LangGraph Integration
```python
# 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!
---
## 🏗️ Deployment
The agent runner 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. In this example, we set the endpoint path to `/process`. After deployment, you can access the service at `http://localhost:8090/process`.
```python
from agentscope_runtime.engine.deployers import LocalDeployManager
# Create deployment manager
deploy_manager = LocalDeployManager(
host="localhost",
port=8090,
)
# Deploy the agent as a streaming service
deploy_result = await runner.deploy(
deploy_manager=deploy_manager,
endpoint_path="/process",
stream=True, # Enable streaming responses
)
```
---
## 🤝 Contributing
We welcome contributions from the community! Here's how you can help:
### 🐛 Bug Reports
- Use GitHub Issues to report bugs
- Include detailed reproduction steps
- Provide system information and logs
### 💡 Feature Requests
- Discuss new ideas in GitHub Discussions
- Follow the feature request template
- Consider implementation feasibility
### 🔧 Code Contributions
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
For detailed contributing guidelines, please see [CONTRIBUTE](cookbook/en/contribute.md).
---
## 📄 License
AgentScope Runtime is released under the [Apache License 2.0](LICENSE).
```
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.
```
## Contributors ✨
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
[](#contributors-)
<!-- ALL-CONTRIBUTORS-BADGE:END -->
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
<tbody>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/rayrayraykk"><img src="https://avatars.githubusercontent.com/u/39145382?v=4?s=100" width="100px;" alt="Weirui Kuang"/><br /><sub><b>Weirui Kuang</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=rayrayraykk" title="Code">💻</a> <a href="https://github.com/agentscope-ai/agentscope-runtime/pulls?q=is%3Apr+reviewed-by%3Arayrayraykk" title="Reviewed Pull Requests">👀</a> <a href="#maintenance-rayrayraykk" title="Maintenance">🚧</a> <a href="#projectManagement-rayrayraykk" title="Project Management">📆</a></td>
<td align="center" valign="top" width="14.28%"><a href="http://www.bruceluo.net/"><img src="https://avatars.githubusercontent.com/u/7297307?v=4?s=100" width="100px;" alt="Bruce Luo"/><br /><sub><b>Bruce Luo</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=zhilingluo" title="Code">💻</a> <a href="https://github.com/agentscope-ai/agentscope-runtime/pulls?q=is%3Apr+reviewed-by%3Azhilingluo" title="Reviewed Pull Requests">👀</a> <a href="#example-zhilingluo" title="Examples">💡</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/zzhangpurdue"><img src="https://avatars.githubusercontent.com/u/5746653?v=4?s=100" width="100px;" alt="Zhicheng Zhang"/><br /><sub><b>Zhicheng Zhang</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=zzhangpurdue" title="Code">💻</a> <a href="https://github.com/agentscope-ai/agentscope-runtime/pulls?q=is%3Apr+reviewed-by%3Azzhangpurdue" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=zzhangpurdue" title="Documentation">📖</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/ericczq"><img src="https://avatars.githubusercontent.com/u/116273607?v=4?s=100" width="100px;" alt="ericczq"/><br /><sub><b>ericczq</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=ericczq" title="Code">💻</a> <a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=ericczq" title="Documentation">📖</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/qbc2016"><img src="https://avatars.githubusercontent.com/u/22984042?v=4?s=100" width="100px;" alt="qbc"/><br /><sub><b>qbc</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/pulls?q=is%3Apr+reviewed-by%3Aqbc2016" title="Reviewed Pull Requests">👀</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/rankesterc"><img src="https://avatars.githubusercontent.com/u/114560457?v=4?s=100" width="100px;" alt="Ran Chen"/><br /><sub><b>Ran Chen</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=rankesterc" title="Code">💻</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/jinliyl"><img src="https://avatars.githubusercontent.com/u/6469360?v=4?s=100" width="100px;" alt="jinliyl"/><br /><sub><b>jinliyl</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=jinliyl" title="Code">💻</a> <a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=jinliyl" title="Documentation">📖</a></td>
</tr>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/Osier-Yi"><img src="https://avatars.githubusercontent.com/u/8287381?v=4?s=100" width="100px;" alt="Osier-Yi"/><br /><sub><b>Osier-Yi</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=Osier-Yi" title="Code">💻</a> <a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=Osier-Yi" title="Documentation">📖</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/kevinlin09"><img src="https://avatars.githubusercontent.com/u/26913335?v=4?s=100" width="100px;" alt="Kevin Lin"/><br /><sub><b>Kevin Lin</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=kevinlin09" title="Code">💻</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://davdgao.github.io/"><img src="https://avatars.githubusercontent.com/u/102287034?v=4?s=100" width="100px;" alt="DavdGao"/><br /><sub><b>DavdGao</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/pulls?q=is%3Apr+reviewed-by%3ADavdGao" title="Reviewed Pull Requests">👀</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/FLyLeaf-coder"><img src="https://avatars.githubusercontent.com/u/122603493?v=4?s=100" width="100px;" alt="FlyLeaf"/><br /><sub><b>FlyLeaf</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=FLyLeaf-coder" title="Code">💻</a> <a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=FLyLeaf-coder" title="Documentation">📖</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/jinghuan-Chen"><img src="https://avatars.githubusercontent.com/u/42742857?v=4?s=100" width="100px;" alt="jinghuan-Chen"/><br /><sub><b>jinghuan-Chen</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=jinghuan-Chen" title="Code">💻</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/Sodawyx"><img src="https://avatars.githubusercontent.com/u/34974468?v=4?s=100" width="100px;" alt="Yuxuan Wu"/><br /><sub><b>Yuxuan Wu</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=Sodawyx" title="Code">💻</a> <a href="https://github.com/agentscope-ai/agentscope-runtime/commits?author=Sodawyx" title="Documentation">📖</a></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/TianYu92"><img src="https://avatars.githubusercontent.com/u/12960468?v=4?s=100" width="100px;" alt="Fear1es5"/><br /><sub><b>Fear1es5</b></sub></a><br /><a href="https://github.com/agentscope-ai/agentscope-runtime/issues?q=author%3ATianYu92" title="Bug reports">🐛</a></td>
</tr>
</tbody>
<tfoot>
<tr>
<td align="center" size="13px" colspan="7">
<img src="https://raw.githubusercontent.com/all-contributors/all-contributors-cli/1b8533af435da9854653492b1327a23a4dbd0a10/assets/logo-small.svg">
<a href="https://all-contributors.js.org/docs/en/bot/usage">Add your contributions</a>
</img>
</td>
</tr>
</tfoot>
</table>
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
