agentscope-runtime 0.1.5b1__py3-none-any.whl → 0.2.0b1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. agentscope_runtime/common/__init__.py +0 -0
  2. agentscope_runtime/common/collections/in_memory_mapping.py +27 -0
  3. agentscope_runtime/common/collections/redis_mapping.py +42 -0
  4. agentscope_runtime/common/container_clients/__init__.py +0 -0
  5. agentscope_runtime/common/container_clients/agentrun_client.py +1098 -0
  6. agentscope_runtime/common/container_clients/docker_client.py +250 -0
  7. agentscope_runtime/engine/__init__.py +12 -0
  8. agentscope_runtime/engine/agents/agentscope_agent.py +488 -0
  9. agentscope_runtime/engine/agents/agno_agent.py +19 -18
  10. agentscope_runtime/engine/agents/autogen_agent.py +13 -8
  11. agentscope_runtime/engine/agents/utils.py +53 -0
  12. agentscope_runtime/engine/app/__init__.py +6 -0
  13. agentscope_runtime/engine/app/agent_app.py +239 -0
  14. agentscope_runtime/engine/app/base_app.py +181 -0
  15. agentscope_runtime/engine/app/celery_mixin.py +92 -0
  16. agentscope_runtime/engine/deployers/base.py +1 -0
  17. agentscope_runtime/engine/deployers/cli_fc_deploy.py +72 -12
  18. agentscope_runtime/engine/deployers/kubernetes_deployer.py +12 -5
  19. agentscope_runtime/engine/deployers/local_deployer.py +61 -3
  20. agentscope_runtime/engine/deployers/modelstudio_deployer.py +77 -27
  21. agentscope_runtime/engine/deployers/utils/docker_image_utils/docker_image_builder.py +3 -3
  22. agentscope_runtime/engine/deployers/utils/docker_image_utils/runner_image_factory.py +9 -0
  23. agentscope_runtime/engine/deployers/utils/package_project_utils.py +234 -3
  24. agentscope_runtime/engine/deployers/utils/service_utils/fastapi_factory.py +567 -7
  25. agentscope_runtime/engine/deployers/utils/service_utils/standalone_main.py.j2 +211 -0
  26. agentscope_runtime/engine/deployers/utils/wheel_packager.py +1 -1
  27. agentscope_runtime/engine/helpers/helper.py +60 -41
  28. agentscope_runtime/engine/runner.py +35 -24
  29. agentscope_runtime/engine/schemas/agent_schemas.py +42 -0
  30. agentscope_runtime/engine/schemas/modelstudio_llm.py +14 -14
  31. agentscope_runtime/engine/services/sandbox_service.py +62 -70
  32. agentscope_runtime/engine/services/tablestore_memory_service.py +304 -0
  33. agentscope_runtime/engine/services/tablestore_rag_service.py +143 -0
  34. agentscope_runtime/engine/services/tablestore_session_history_service.py +293 -0
  35. agentscope_runtime/engine/services/utils/__init__.py +0 -0
  36. agentscope_runtime/engine/services/utils/tablestore_service_utils.py +352 -0
  37. agentscope_runtime/engine/tracing/__init__.py +9 -3
  38. agentscope_runtime/engine/tracing/asyncio_util.py +24 -0
  39. agentscope_runtime/engine/tracing/base.py +66 -34
  40. agentscope_runtime/engine/tracing/local_logging_handler.py +45 -31
  41. agentscope_runtime/engine/tracing/message_util.py +528 -0
  42. agentscope_runtime/engine/tracing/tracing_metric.py +20 -8
  43. agentscope_runtime/engine/tracing/tracing_util.py +130 -0
  44. agentscope_runtime/engine/tracing/wrapper.py +794 -169
  45. agentscope_runtime/sandbox/__init__.py +2 -0
  46. agentscope_runtime/sandbox/box/base/__init__.py +4 -0
  47. agentscope_runtime/sandbox/box/base/base_sandbox.py +6 -4
  48. agentscope_runtime/sandbox/box/browser/__init__.py +4 -0
  49. agentscope_runtime/sandbox/box/browser/browser_sandbox.py +10 -14
  50. agentscope_runtime/sandbox/box/dummy/__init__.py +4 -0
  51. agentscope_runtime/sandbox/box/dummy/dummy_sandbox.py +2 -1
  52. agentscope_runtime/sandbox/box/filesystem/__init__.py +4 -0
  53. agentscope_runtime/sandbox/box/filesystem/filesystem_sandbox.py +10 -7
  54. agentscope_runtime/sandbox/box/gui/__init__.py +4 -0
  55. agentscope_runtime/sandbox/box/gui/box/__init__.py +0 -0
  56. agentscope_runtime/sandbox/box/gui/gui_sandbox.py +81 -0
  57. agentscope_runtime/sandbox/box/sandbox.py +5 -2
  58. agentscope_runtime/sandbox/box/shared/routers/generic.py +20 -1
  59. agentscope_runtime/sandbox/box/training_box/__init__.py +4 -0
  60. agentscope_runtime/sandbox/box/training_box/training_box.py +10 -15
  61. agentscope_runtime/sandbox/build.py +143 -58
  62. agentscope_runtime/sandbox/client/http_client.py +87 -59
  63. agentscope_runtime/sandbox/client/training_client.py +0 -1
  64. agentscope_runtime/sandbox/constant.py +27 -1
  65. agentscope_runtime/sandbox/custom/custom_sandbox.py +7 -6
  66. agentscope_runtime/sandbox/custom/example.py +4 -3
  67. agentscope_runtime/sandbox/enums.py +1 -0
  68. agentscope_runtime/sandbox/manager/sandbox_manager.py +212 -106
  69. agentscope_runtime/sandbox/manager/server/app.py +82 -14
  70. agentscope_runtime/sandbox/manager/server/config.py +50 -3
  71. agentscope_runtime/sandbox/model/container.py +12 -23
  72. agentscope_runtime/sandbox/model/manager_config.py +93 -5
  73. agentscope_runtime/sandbox/registry.py +1 -1
  74. agentscope_runtime/sandbox/tools/gui/__init__.py +7 -0
  75. agentscope_runtime/sandbox/tools/gui/tool.py +77 -0
  76. agentscope_runtime/sandbox/tools/mcp_tool.py +6 -2
  77. agentscope_runtime/sandbox/tools/tool.py +4 -0
  78. agentscope_runtime/sandbox/utils.py +124 -0
  79. agentscope_runtime/version.py +1 -1
  80. {agentscope_runtime-0.1.5b1.dist-info → agentscope_runtime-0.2.0b1.dist-info}/METADATA +209 -101
  81. {agentscope_runtime-0.1.5b1.dist-info → agentscope_runtime-0.2.0b1.dist-info}/RECORD +95 -79
  82. agentscope_runtime/engine/agents/agentscope_agent/__init__.py +0 -6
  83. agentscope_runtime/engine/agents/agentscope_agent/agent.py +0 -401
  84. agentscope_runtime/engine/agents/agentscope_agent/hooks.py +0 -169
  85. agentscope_runtime/engine/agents/llm_agent.py +0 -51
  86. agentscope_runtime/engine/llms/__init__.py +0 -3
  87. agentscope_runtime/engine/llms/base_llm.py +0 -60
  88. agentscope_runtime/engine/llms/qwen_llm.py +0 -47
  89. agentscope_runtime/sandbox/manager/collections/in_memory_mapping.py +0 -22
  90. agentscope_runtime/sandbox/manager/collections/redis_mapping.py +0 -26
  91. agentscope_runtime/sandbox/manager/container_clients/__init__.py +0 -10
  92. agentscope_runtime/sandbox/manager/container_clients/docker_client.py +0 -422
  93. /agentscope_runtime/{sandbox/manager → common}/collections/__init__.py +0 -0
  94. /agentscope_runtime/{sandbox/manager → common}/collections/base_mapping.py +0 -0
  95. /agentscope_runtime/{sandbox/manager → common}/collections/base_queue.py +0 -0
  96. /agentscope_runtime/{sandbox/manager → common}/collections/base_set.py +0 -0
  97. /agentscope_runtime/{sandbox/manager → common}/collections/in_memory_queue.py +0 -0
  98. /agentscope_runtime/{sandbox/manager → common}/collections/in_memory_set.py +0 -0
  99. /agentscope_runtime/{sandbox/manager → common}/collections/redis_queue.py +0 -0
  100. /agentscope_runtime/{sandbox/manager → common}/collections/redis_set.py +0 -0
  101. /agentscope_runtime/{sandbox/manager → common}/container_clients/base_client.py +0 -0
  102. /agentscope_runtime/{sandbox/manager → common}/container_clients/kubernetes_client.py +0 -0
  103. {agentscope_runtime-0.1.5b1.dist-info → agentscope_runtime-0.2.0b1.dist-info}/WHEEL +0 -0
  104. {agentscope_runtime-0.1.5b1.dist-info → agentscope_runtime-0.2.0b1.dist-info}/entry_points.txt +0 -0
  105. {agentscope_runtime-0.1.5b1.dist-info → agentscope_runtime-0.2.0b1.dist-info}/licenses/LICENSE +0 -0
  106. {agentscope_runtime-0.1.5b1.dist-info → agentscope_runtime-0.2.0b1.dist-info}/top_level.txt +0 -0
@@ -0,0 +1,124 @@
1
+ # -*- coding: utf-8 -*-
2
+ import os
3
+ import importlib
4
+ import platform
5
+
6
+ from urllib.parse import urlparse, urlunparse
7
+
8
+ from .constant import REGISTRY, IMAGE_NAMESPACE, IMAGE_TAG
9
+
10
+
11
+ def build_image_uri(
12
+ image_name: str,
13
+ tag: str = None,
14
+ registry: str = None,
15
+ namespace: str = None,
16
+ arm64_compatible: bool = True,
17
+ ) -> str:
18
+ """
19
+ Build a fully qualified Docker image URI.
20
+
21
+ Parameters
22
+ ----------
23
+ image_name : str
24
+ Name of the Docker image without registry/namespace.
25
+ Example: `"runtime-sandbox-base"`.
26
+ tag : str, optional
27
+ Base image tag. Defaults to the global ``IMAGE_TAG`` if not provided.
28
+ registry : str, optional
29
+ Docker registry address. Defaults to the global ``REGISTRY``.
30
+ If empty or whitespace, registry prefix will be omitted.
31
+ namespace : str, optional
32
+ Docker image namespace. Defaults to the global ``IMAGE_NAMESPACE``.
33
+ arm64_compatible : bool, optional
34
+ Whether the image is ARM64-compatible without special tagging.
35
+ If ``True`` (default), the tag is returned unchanged.
36
+ If ``False``, the function will detect the current machine
37
+ architecture and append ``-arm64`` to the tag if running on ARM64 (
38
+ e.g., ``arm64``, ``aarch64``).
39
+
40
+ Returns
41
+ -------
42
+ str
43
+ Fully qualified Docker image URI in the form:
44
+ ``<registry>/<namespace>/<image_name>:<tag>`` or
45
+ ``<namespace>/<image_name>:<tag>`` if registry is omitted.
46
+
47
+ Examples
48
+ --------
49
+ >>> build_image_uri("runtime-sandbox-base")
50
+ 'agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:latest'
51
+
52
+ >>> build_image_uri("runtime-sandbox-base", tag="v1.2.3")
53
+ 'agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:v1.2.3'
54
+
55
+ >>> build_image_uri("runtime-sandbox-base", registry="")
56
+ 'agentscope/runtime-sandbox-base:latest'
57
+
58
+ >>> build_image_uri("runtime-sandbox-base", arm64_compatible=False)
59
+ 'agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime
60
+ -sandbox-base:latest-arm64'
61
+ # (Above example assumes running on ARM64 machine)
62
+ """
63
+ reg = registry if registry is not None else REGISTRY
64
+ reg = "" if reg.strip() == "" else f"{reg.strip()}/"
65
+
66
+ final_namespace = namespace if namespace is not None else IMAGE_NAMESPACE
67
+ final_tag = tag or IMAGE_TAG
68
+
69
+ # TODO: make manifest compatible and remove this
70
+ # Adjust tag based on ARM64 compatibility
71
+ if not arm64_compatible:
72
+ machine = platform.machine().lower()
73
+ if "arm" in machine or "aarch64" in machine:
74
+ final_tag = f"{final_tag}-arm64"
75
+
76
+ return f"{reg}{final_namespace}/{image_name}:{final_tag}"
77
+
78
+
79
+ def dynamic_import(ext: str):
80
+ """
81
+ Dynamically import a Python file or module.
82
+
83
+ Parameters
84
+ ----------
85
+ ext : str
86
+ File path to a Python script OR a module name to import.
87
+
88
+ Returns
89
+ -------
90
+ module : object
91
+ The imported Python module/object.
92
+ """
93
+ if os.path.isfile(ext):
94
+ module_name = os.path.splitext(os.path.basename(ext))[0]
95
+ spec = importlib.util.spec_from_file_location(module_name, ext)
96
+ module = importlib.util.module_from_spec(spec)
97
+ spec.loader.exec_module(module)
98
+ return module
99
+ else:
100
+ return importlib.import_module(ext)
101
+
102
+
103
+ def http_to_ws(url, use_localhost=True):
104
+ parsed = urlparse(url)
105
+ ws_scheme = "wss" if parsed.scheme == "https" else "ws"
106
+
107
+ hostname = parsed.hostname
108
+ if use_localhost and hostname == "127.0.0.1":
109
+ hostname = "localhost"
110
+
111
+ if parsed.port:
112
+ new_netloc = f"{hostname}:{parsed.port}"
113
+ else:
114
+ new_netloc = hostname
115
+
116
+ ws_url = urlunparse(parsed._replace(scheme=ws_scheme, netloc=new_netloc))
117
+ return ws_url
118
+
119
+
120
+ def get_platform():
121
+ machine = platform.machine().lower()
122
+ if "arm" in machine or "aarch64" in machine:
123
+ return "linux/arm64"
124
+ return "linux/amd64"
@@ -1,2 +1,2 @@
1
1
  # -*- coding: utf-8 -*-
2
- __version__ = "0.1.5b1"
2
+ __version__ = "v0.2.0b1"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agentscope-runtime
3
- Version: 0.1.5b1
3
+ Version: 0.2.0b1
4
4
  Summary: A production-ready runtime framework for agent applications, providing secure sandboxed execution environments and scalable deployment solutions with multi-framework support.
5
5
  Requires-Python: >=3.10
6
6
  Description-Content-Type: text/markdown
@@ -8,52 +8,56 @@ License-File: LICENSE
8
8
  Requires-Dist: mcp>=1.13
9
9
  Requires-Dist: fastapi>=0.104.0
10
10
  Requires-Dist: uvicorn[standard]>=0.24.0
11
- Requires-Dist: openai>=1.108.1
11
+ Requires-Dist: openai
12
12
  Requires-Dist: pydantic>=2.11.7
13
13
  Requires-Dist: requests>=2.32.4
14
+ Requires-Dist: agentscope>=1.0.6
15
+ Requires-Dist: docker>=7.1.0
16
+ Requires-Dist: redis>=6.0.0
17
+ Requires-Dist: oss2>=2.19.1
18
+ Requires-Dist: pydantic-settings>=2.9.1
19
+ Requires-Dist: python-dotenv>=1.0.1
20
+ Requires-Dist: kubernetes>=33.1.0
21
+ Requires-Dist: shortuuid>=1.0.13
22
+ Requires-Dist: celery[redis]>=5.3.1
23
+ Requires-Dist: a2a-sdk>=0.3.0
14
24
  Provides-Extra: dev
15
25
  Requires-Dist: pytest>=8.3.5; extra == "dev"
16
26
  Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
17
27
  Requires-Dist: pre-commit>=4.2.0; extra == "dev"
18
- Requires-Dist: jupyter-book>=1.0.4.post1; extra == "dev"
28
+ Requires-Dist: jupyter-book<2.0.0,>=1.0.4.post1; extra == "dev"
19
29
  Requires-Dist: furo>=2025.7.19; extra == "dev"
20
30
  Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
21
31
  Requires-Dist: fakeredis>=2.31.0; extra == "dev"
22
32
  Requires-Dist: sphinx-autoapi>=3.6.0; extra == "dev"
23
- Provides-Extra: sandbox
24
- Requires-Dist: docker>=7.1.0; extra == "sandbox"
25
- Requires-Dist: steel-sdk>=0.1.0; extra == "sandbox"
26
- Requires-Dist: redis>=6.0.0b2; extra == "sandbox"
27
- Requires-Dist: oss2>=2.19.1; extra == "sandbox"
28
- Requires-Dist: pydantic-settings>=2.9.1; extra == "sandbox"
29
- Requires-Dist: dotenv>=0.9.9; extra == "sandbox"
30
- Requires-Dist: kubernetes>=33.1.0; extra == "sandbox"
31
- Requires-Dist: shortuuid>=1.0.13; extra == "sandbox"
32
- Provides-Extra: agentscope
33
- Requires-Dist: agentscope>=1.0.1; extra == "agentscope"
34
33
  Provides-Extra: langgraph
35
34
  Requires-Dist: langgraph>=0.5.3; extra == "langgraph"
36
35
  Provides-Extra: agno
37
36
  Requires-Dist: agno<2.0.0,>=1.7.5; extra == "agno"
38
- Provides-Extra: a2a
39
- Requires-Dist: a2a-sdk>=0.3.0; extra == "a2a"
40
37
  Provides-Extra: autogen
41
38
  Requires-Dist: autogen-agentchat>=0.7.4; extra == "autogen"
42
39
  Requires-Dist: autogen-ext[openai]>=0.7.4; extra == "autogen"
40
+ Provides-Extra: agentrun
41
+ Requires-Dist: alibabacloud-agentrun20250910>=1.0.0; extra == "agentrun"
42
+ Requires-Dist: alibabacloud_tea_openapi>=0.4.0; extra == "agentrun"
43
43
  Provides-Extra: langchain-rag
44
44
  Requires-Dist: langchain>=0.3.25; extra == "langchain-rag"
45
- Requires-Dist: pymilvus>=2.6.0; extra == "langchain-rag"
45
+ Requires-Dist: pymilvus[milvus-lite]>=2.6.0; extra == "langchain-rag"
46
46
  Requires-Dist: langchain-community>=0.3.27; extra == "langchain-rag"
47
47
  Requires-Dist: langchain-milvus>=0.2.1; extra == "langchain-rag"
48
48
  Requires-Dist: bs4>=0.0.2; extra == "langchain-rag"
49
49
  Provides-Extra: llamaindex-rag
50
50
  Requires-Dist: llama-index>=0.13.4; extra == "llamaindex-rag"
51
- Requires-Dist: pymilvus>=2.6.0; extra == "llamaindex-rag"
51
+ Requires-Dist: pymilvus[milvus-lite]>=2.6.0; extra == "llamaindex-rag"
52
52
  Requires-Dist: llama-index-vector-stores-milvus>=0.9.1; extra == "llamaindex-rag"
53
53
  Requires-Dist: llama-index-readers-web>=0.5.1; extra == "llamaindex-rag"
54
54
  Requires-Dist: llama-index-embeddings-langchain>=0.4.0; extra == "llamaindex-rag"
55
- Requires-Dist: langchain-community>=0.3.27; extra == "llamaindex-rag"
55
+ Requires-Dist: llama-index-embeddings-dashscope>=0.4.0; extra == "llamaindex-rag"
56
56
  Requires-Dist: bs4>=0.0.2; extra == "llamaindex-rag"
57
+ Provides-Extra: aliyun-tablestore-ext
58
+ Requires-Dist: tablestore-for-agent-memory>=1.1.0; extra == "aliyun-tablestore-ext"
59
+ Requires-Dist: dashscope>=1.24.4; extra == "aliyun-tablestore-ext"
60
+ Requires-Dist: langchain-community>=0.3.27; extra == "aliyun-tablestore-ext"
57
61
  Provides-Extra: memory-ext
58
62
  Requires-Dist: reme-ai==0.1.9; python_full_version >= "3.12" and extra == "memory-ext"
59
63
  Requires-Dist: mem0ai>=0.1.117; extra == "memory-ext"
@@ -68,8 +72,6 @@ Requires-Dist: alibabacloud-credentials; extra == "deployment"
68
72
  Requires-Dist: jinja2; extra == "deployment"
69
73
  Requires-Dist: psutil; extra == "deployment"
70
74
  Requires-Dist: shortuuid>=1.0.13; extra == "deployment"
71
- Requires-Dist: docker>=7.1.0; extra == "deployment"
72
- Requires-Dist: kubernetes>=33.1.0; extra == "deployment"
73
75
  Requires-Dist: PyYAML; extra == "deployment"
74
76
  Requires-Dist: oss2>=2.19.1; extra == "deployment"
75
77
  Dynamic: license-file
@@ -78,9 +80,11 @@ Dynamic: license-file
78
80
 
79
81
  # AgentScope Runtime
80
82
 
83
+ [![GitHub Repo](https://img.shields.io/badge/GitHub-Repo-black.svg?logo=github)](https://github.com/agentscope-ai/agentscope-runtime)
81
84
  [![PyPI](https://img.shields.io/pypi/v/agentscope-runtime?label=PyPI&color=brightgreen&logo=python)](https://pypi.org/project/agentscope-runtime/)
85
+ [![Downloads](https://static.pepy.tech/badge/agentscope-runtime)](https://pepy.tech/project/agentscope-runtime)
82
86
  [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg?logo=python&label=Python)](https://python.org)
83
- [![License](https://img.shields.io/badge/license-Apache%202.0-red.svg?logo=apache&label=Liscnese)](LICENSE)
87
+ [![License](https://img.shields.io/badge/license-Apache%202.0-red.svg?logo=apache&label=License)](LICENSE)
84
88
  [![Code Style](https://img.shields.io/badge/code%20style-black-black.svg?logo=python&label=CodeStyle)](https://github.com/psf/black)
85
89
  [![GitHub Stars](https://img.shields.io/github/stars/agentscope-ai/agentscope-runtime?style=flat&logo=github&color=yellow&label=Stars)](https://github.com/agentscope-ai/agentscope-runtime/stargazers)
86
90
  [![GitHub Forks](https://img.shields.io/github/forks/agentscope-ai/agentscope-runtime?style=flat&logo=github&color=purple&label=Forks)](https://github.com/agentscope-ai/agentscope-runtime/network)
@@ -94,6 +98,7 @@ Dynamic: license-file
94
98
 
95
99
  [[Cookbook]](https://runtime.agentscope.io/)
96
100
  [[中文README]](README_zh.md)
101
+ [[Samples]](https://github.com/agentscope-ai/agentscope-samples)
97
102
 
98
103
  **A Production-Ready Runtime Framework for Intelligent Agent Applications**
99
104
 
@@ -103,6 +108,13 @@ Dynamic: license-file
103
108
 
104
109
  ---
105
110
 
111
+ ## 🆕 NEWS
112
+
113
+ * **[2025-10]** We released `v0.2.0` — introducing **`AgentApp` API server support**, enabling easy use of agent applications and custom API endpoints through synchronous, asynchronous, and streaming interfaces. Check our [cookbook](https://runtime.agentscope.io/en/agent_app.html) for more details.
114
+ * **[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.
115
+
116
+ ---
117
+
106
118
  ## ✨ Key Features
107
119
 
108
120
  - **🏗️ Deployment Infrastructure**: Built-in services for session management, memory, and sandbox environment control
@@ -150,9 +162,6 @@ From PyPI:
150
162
  ```bash
151
163
  # Install core dependencies
152
164
  pip install agentscope-runtime
153
-
154
- # Install sandbox dependencies
155
- pip install "agentscope-runtime[sandbox]"
156
165
  ```
157
166
 
158
167
  (Optional) From source:
@@ -164,74 +173,191 @@ cd agentscope-runtime
164
173
 
165
174
  # Install core dependencies
166
175
  pip install -e .
167
-
168
- # Install sandbox dependencies
169
- pip install -e ".[sandbox]"
170
176
  ```
171
177
 
172
- ### Basic Agent Usage Example
178
+ ### Basic Agent App Example
179
+
180
+ 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.
173
181
 
174
- This example demonstrates how to create a simple LLM agent using AgentScope Runtime and stream responses from the Qwen model.
175
182
 
176
183
  ```python
177
- import asyncio
178
184
  import os
179
- from agentscope_runtime.engine import Runner
180
- from agentscope_runtime.engine.agents.llm_agent import LLMAgent
181
- from agentscope_runtime.engine.llms import QwenLLM
182
- from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest
183
- from agentscope_runtime.engine.services.context_manager import ContextManager
184
-
185
-
186
- async def main():
187
- # Set up the language model and agent
188
- model = QwenLLM(
189
- model_name="qwen-turbo",
190
- api_key=os.getenv("DASHSCOPE_API_KEY"),
191
- )
192
- llm_agent = LLMAgent(model=model, name="llm_agent")
193
-
194
- async with ContextManager() as context_manager:
195
- runner = Runner(agent=llm_agent, context_manager=context_manager)
196
-
197
- # Create a request and stream the response
198
- request = AgentRequest(
199
- input=[
200
- {
201
- "role": "user",
202
- "content": [
203
- {
204
- "type": "text",
205
- "text": "What is the capital of France?",
206
- },
207
- ],
208
- },
209
- ],
210
- )
211
-
212
- async for message in runner.stream_query(request=request):
213
- if hasattr(message, "text"):
214
- print(f"Streamed Answer: {message.text}")
215
-
216
-
217
- asyncio.run(main())
185
+
186
+ from agentscope_runtime.engine import AgentApp
187
+ from agentscope_runtime.engine.agents.agentscope_agent import AgentScopeAgent
188
+
189
+ from agentscope.agent import ReActAgent
190
+ from agentscope.model import OpenAIChatModel
191
+
192
+
193
+ agent = AgentScopeAgent(
194
+ name="Friday",
195
+ model=OpenAIChatModel(
196
+ "gpt-4",
197
+ api_key=os.getenv("OPENAI_API_KEY"),
198
+ ),
199
+ agent_config={
200
+ "sys_prompt": "You're a helpful assistant named Friday.",
201
+ },
202
+ agent_builder=ReActAgent, # Or use your own agent builder
203
+ )
204
+ app = AgentApp(agent=agent, endpoint_path="/process")
205
+
206
+ app.run(host="0.0.0.0", port=8090)
207
+ ```
208
+
209
+ The server will start and listen on: `http://localhost:8090/process`. You can send JSON input to the API using `curl`:
210
+
211
+ ```bash
212
+ curl -N \
213
+ -X POST "http://localhost:8090/process" \
214
+ -H "Content-Type: application/json" \
215
+ -d '{
216
+ "input": [
217
+ {
218
+ "role": "user",
219
+ "content": [
220
+ { "type": "text", "text": "What is the capital of France?" }
221
+ ]
222
+ }
223
+ ]
224
+ }'
225
+ ```
226
+
227
+ You’ll see output streamed in **Server-Sent Events (SSE)** format:
228
+
229
+ ```bash
230
+ data: {"sequence_number":0,"object":"response","status":"created", ... }
231
+ data: {"sequence_number":1,"object":"response","status":"in_progress", ... }
232
+ data: {"sequence_number":2,"object":"content","status":"in_progress","text":"The" }
233
+ data: {"sequence_number":3,"object":"content","status":"in_progress","text":" capital of France is Paris." }
234
+ data: {"sequence_number":4,"object":"message","status":"completed","text":"The capital of France is Paris." }
218
235
  ```
219
236
 
220
237
  ### Basic Sandbox Usage Example
221
238
 
222
- This example demonstrates how to create sandboxed and execute tool within the sandbox.
239
+ 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):
240
+
241
+ > [!NOTE]
242
+ >
243
+ > 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.
244
+ >
245
+ > 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)
246
+
247
+ #### Base Sandbox
248
+
249
+ Use for running **Python code** or **shell commands** in an isolated environment.
223
250
 
224
251
  ```python
225
252
  from agentscope_runtime.sandbox import BaseSandbox
226
253
 
227
254
  with BaseSandbox() as box:
228
- print(box.run_ipython_cell(code="print('hi')"))
229
- print(box.run_shell_command(command="echo hello"))
255
+ # By default, pulls `agentscope/runtime-sandbox-base:latest` from DockerHub
256
+ print(box.list_tools()) # List all available tools
257
+ print(box.run_ipython_cell(code="print('hi')")) # Run Python code
258
+ print(box.run_shell_command(command="echo hello")) # Run shell command
259
+ input("Press Enter to continue...")
230
260
  ```
231
261
 
232
- > [!NOTE]
233
- >
234
- > 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.
262
+ #### GUI Sandbox
263
+
264
+ Provides a **virtual desktop** environment for mouse, keyboard, and screen operations.
265
+
266
+ <img src="https://img.alicdn.com/imgextra/i2/O1CN01df5SaM1xKFQP4KGBW_!!6000000006424-2-tps-2958-1802.png" alt="GUI Sandbox" width="800" height="500">
267
+
268
+ ```python
269
+ from agentscope_runtime.sandbox import GuiSandbox
270
+
271
+ with GuiSandbox() as box:
272
+ # By default, pulls `agentscope/runtime-sandbox-gui:latest` from DockerHub
273
+ print(box.list_tools()) # List all available tools
274
+ print(box.desktop_url) # Web desktop access URL
275
+ print(box.computer_use(action="get_cursor_position")) # Get mouse cursor position
276
+ print(box.computer_use(action="get_screenshot")) # Capture screenshot
277
+ input("Press Enter to continue...")
278
+ ```
279
+
280
+ #### Browser Sandbox
281
+
282
+ A GUI-based sandbox with **browser operations** inside an isolated sandbox.
283
+
284
+ <img src="https://img.alicdn.com/imgextra/i4/O1CN01OIq1dD1gAJMcm0RFR_!!6000000004101-2-tps-2734-1684.png" alt="GUI Sandbox" width="800" height="500">
285
+
286
+ ```python
287
+ from agentscope_runtime.sandbox import BrowserSandbox
288
+
289
+ with BrowserSandbox() as box:
290
+ # By default, pulls `agentscope/runtime-sandbox-browser:latest` from DockerHub
291
+ print(box.list_tools()) # List all available tools
292
+ print(box.desktop_url) # Web desktop access URL
293
+ box.browser_navigate("https://www.google.com/") # Open a webpage
294
+ input("Press Enter to continue...")
295
+ ```
296
+
297
+ #### Filesystem Sandbox
298
+
299
+ A GUI-based sandbox with **file system operations** such as creating, reading, and deleting files.
300
+
301
+ <img src="https://img.alicdn.com/imgextra/i3/O1CN01VocM961vK85gWbJIy_!!6000000006153-2-tps-2730-1686.png" alt="GUI Sandbox" width="800" height="500">
302
+
303
+ ```python
304
+ from agentscope_runtime.sandbox import FilesystemSandbox
305
+
306
+ with FilesystemSandbox() as box:
307
+ # By default, pulls `agentscope/runtime-sandbox-filesystem:latest` from DockerHub
308
+ print(box.list_tools()) # List all available tools
309
+ print(box.desktop_url) # Web desktop access URL
310
+ box.create_directory("test") # Create a directory
311
+ input("Press Enter to continue...")
312
+ ```
313
+
314
+ #### Configuring Sandbox Image Registry, Namespace, and Tag
315
+
316
+ ##### 1. Registry
317
+
318
+ 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:
319
+
320
+ ```bash
321
+ export RUNTIME_SANDBOX_REGISTRY="agentscope-registry.ap-southeast-1.cr.aliyuncs.com"
322
+ ```
323
+
324
+ ##### 2. Namespace
325
+
326
+ A namespace is used to distinguish images of different teams or projects. You can customize the namespace via an environment variable:
327
+
328
+ ```bash
329
+ export RUNTIME_SANDBOX_IMAGE_NAMESPACE="agentscope"
330
+ ```
331
+
332
+ For example, here `agentscope` will be used as part of the image path.
333
+
334
+ ##### 3. Tag
335
+
336
+ An image tag specifies the version of the image, for example:
337
+
338
+ ```bash
339
+ export RUNTIME_SANDBOX_IMAGE_TAG="preview"
340
+ ```
341
+
342
+ Details:
343
+
344
+ - Default is `latest`, which means the image version matches the PyPI latest release.
345
+ - `preview` means the latest preview version built in sync with the **GitHub main branch**.
346
+ - 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).
347
+
348
+ ##### 4. Complete Image Path
349
+
350
+ The sandbox SDK will build the full image path based on the above environment variables:
351
+
352
+ ```bash
353
+ <RUNTIME_SANDBOX_REGISTRY>/<RUNTIME_SANDBOX_IMAGE_NAMESPACE>/runtime-sandbox-base:<RUNTIME_SANDBOX_IMAGE_TAG>
354
+ ```
355
+
356
+ Example:
357
+
358
+ ```bash
359
+ agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:preview
360
+ ```
235
361
 
236
362
  ---
237
363
 
@@ -245,30 +371,7 @@ with BaseSandbox() as box:
245
371
 
246
372
  ---
247
373
 
248
- ## 🔌 Agent Framework Integration
249
-
250
- ### AgentScope Integration
251
-
252
- ```python
253
- # pip install "agentscope-runtime[agentscope]"
254
- import os
255
-
256
- from agentscope.agent import ReActAgent
257
- from agentscope.model import OpenAIChatModel
258
- from agentscope_runtime.engine.agents.agentscope_agent import AgentScopeAgent
259
-
260
- agent = AgentScopeAgent(
261
- name="Friday",
262
- model=OpenAIChatModel(
263
- "gpt-4",
264
- api_key=os.getenv("OPENAI_API_KEY"),
265
- ),
266
- agent_config={
267
- "sys_prompt": "You're a helpful assistant named {name}.",
268
- },
269
- agent_builder=ReActAgent,
270
- )
271
- ```
374
+ ## 🔌 Other Agent Framework Integration
272
375
 
273
376
  ### Agno Integration
274
377
 
@@ -421,7 +524,7 @@ limitations under the License.
421
524
 
422
525
  ## Contributors ✨
423
526
  <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
424
- [![All Contributors](https://img.shields.io/badge/all_contributors-9-orange.svg?style=flat-square)](#contributors-)
527
+ [![All Contributors](https://img.shields.io/badge/all_contributors-14-orange.svg?style=flat-square)](#contributors-)
425
528
  <!-- ALL-CONTRIBUTORS-BADGE:END -->
426
529
 
427
530
  Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -443,6 +546,11 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
443
546
  <tr>
444
547
  <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>
445
548
  <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>
549
+ <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>
550
+ <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>
551
+ <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>
552
+ <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>
553
+ <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>
446
554
  </tr>
447
555
  </tbody>
448
556
  <tfoot>