AgentScope Runtime: a sandboxed deployment layer that is being folded into AgentScope 2.0

The gap AgentScope Runtime was built to fill

Most agent frameworks stop at the loop: prompt, tool call, observation, repeat. Getting that loop in front of a caller is a different job. You need an HTTP surface, a streaming protocol, a place for tool code to run without touching the host, and some way to move the whole thing onto a cluster. AgentScope Runtime packages those four concerns as one Python library. The README calls them tool sandboxing, Agent-as-a-Service APIs, scalable deployment and full-stack observability, and lists framework compatibility with mainstream agent frameworks as a secondary point.

The intended reader is an engineer who already has agent logic and now has to operate it. The pyproject dependencies reflect that: fastapi and uvicorn for the service layer, docker and kubernetes for isolation and orchestration, redis and celery for background work, a2a-sdk for the Agent-to-Agent protocol. Nothing there is about prompt design. The library assumes the reasoning part is someone else's problem, and that the hard part is execution and delivery.

AgentApp, the three-stage pattern, and where sandboxing sits

The central abstraction is AgentApp. The release notes for v1.1.0 describe a refactor in which AgentApp inherits directly from FastAPI, replacing an earlier factory pattern. That inheritance is the design decision worth noticing: an AgentApp is a FastAPI application, so ordinary FastAPI routes, middleware and dependency injection apply, and the agent endpoints are additions rather than a parallel stack.

The README frames development as three stages, init, query and shutdown. Query is the streaming path, and the README's recommended reading order points at curl over SSE to verify it. Sandboxing is a separate subsystem rather than a decorator on the agent. The README lists Python, Shell, GUI, Browser, Filesystem and Mobile as tool categories that run in an isolated sandbox, and pyproject exposes two console scripts for it, runtime-sandbox-server and runtime-sandbox-mcp, plus runtime-sandbox-builder for images. Deployment is a third subsystem: a DeployManager is documented for local and serverless targets, with access through A2A, a Response API, or the OpenAI SDK in compatible mode.

So the data flow is roughly: caller hits an AgentApp endpoint, the agent decides on a tool call, the call is dispatched to a sandbox process or container rather than executed in the API process, results stream back over SSE, and the deployer decides where the API and its sandboxes live. The README does not document what happens to a sandbox mid-call if the API process restarts, which matters if you plan to run stateful tools.

Install and get a streaming agent API answering curl

The README gives two install paths, PyPI or source. The package requires Python 3.10 or newer. Installing from PyPI is a single command, and the repository ships a setup.py that calls setuptools with no arguments, so a source checkout installs the same way from the repository root.

pip install agentscope-runtime

That install also places the console scripts declared in pyproject, among them agentscope, runtime-sandbox-server, runtime-sandbox-mcp, runtime-sandbox-builder, runtime-fc-deploy and modelstudio-mcp-server. The README's Quick Start is organised around a minimal AgentApp example that exposes a streaming API, and it tells you to verify it with curl against the SSE endpoint. The exact route and payload are in the Quick Start section of the README rather than repeated here, because the README is the source of truth for the request shape. What you should see is an event stream that stays open and emits chunks as the agent produces them, not a single buffered JSON body. If you get one JSON object and the connection closes, you are hitting a non-streaming route.

The sandbox path is separate. The README documents sandbox image registry, namespace and tag configuration, and points at production-grade serverless sandbox deployment as an optional follow-up. Configuration for those lives in the sandbox examples under examples/sandbox/ in the repository. The README does not publish the environment variable names for the registry, namespace and tag settings, so read the example files before writing your own config.

Where this runtime is the wrong tool

The strongest limitation is stated by the project itself. An archive notice at the top of the README says that 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. It recommends migrating, says the repository will remain available in read-only mode for reference, and says it will be archived soon. The last push to the repository was on 2026-06-04. Anyone starting fresh today is starting on a branch of history that the maintainers have already declared closed, and the only supported upgrade path runs through a different repository.

There is a second, quieter limitation. The dependency list is long and opinionated: docker, kubernetes, redis, celery, oss2, dashscope, a2a-sdk. Installing agentscope-runtime pulls a container client and a cluster client into your environment whether or not you deploy to a cluster. For a single-process agent behind one endpoint, that is a lot of surface area to carry for streaming and a FastAPI base class you could get directly.

Third, the sandbox covers Python, Shell, GUI, Browser, Filesystem and Mobile tool categories. If your tools are HTTP calls to SaaS APIs, the isolation layer buys you much less. And the README's own framing of the sandbox as hardened is a claim about the image and the isolation boundary, not a statement about what arbitrary code inside it can reach on the network. The README does not document outbound network policy for sandboxes, so treat that as something to verify in the sandbox examples rather than assume.

How it differs from LangGraph and from a plain FastAPI wrapper

LangGraph and AgentScope Runtime sit at different layers. LangGraph is a graph execution model for agent control flow: you define nodes and edges and it manages state transitions. AgentScope Runtime does not define your control flow at all. It takes an agent, whatever produced it, and gives it a service boundary and an execution boundary. The README lists LangGraph among the frameworks it is compatible with, which is consistent with that reading: LangGraph could plausibly be the thing running inside an AgentApp rather than a substitute for it. If your problem is how the agent decides what to do next, LangGraph is the closer fit. If your problem is that the agent works on your laptop and you cannot put it in front of users safely, that is this project's territory.

The other comparison is the obvious one: write FastAPI yourself and run tool code in a subprocess. That is genuinely less machinery, and for a small number of trusted tools it is the right answer. What you would be reimplementing is the sandbox image build (runtime-sandbox-builder), the sandbox manager server, the MCP bridge, the A2A surface and the DeployManager's serverless path. Whether that is worth it depends entirely on whether you need more than one of them. If you need exactly one, take the smaller thing.

Licence and the cost of staying on v1.1.6

The repository is Apache-2.0, and the LICENSE file is at the repository root. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, with the usual obligations around preserving notices and stating changes. It does not give you any claim on the AgentScope name or marks. This is a description of the licence text, not legal advice; if you are redistributing a modified runtime, have counsel read the NOTICE and attribution requirements for your distribution model.

The upgrade cost is the real one, and it is not a version bump. The README's archive notice says the capabilities moved into AgentScope 2.0, which is a different repository with a different release cadence. Migrating means re-establishing the AgentApp surface, the sandbox configuration and the deployment target against that codebase. The README does not document a migration guide, a compatibility shim, or a mapping from AgentScope Runtime APIs to AgentScope 2.0 APIs. The three releases visible in the repository are v1.1.6 on 2026-05-19 and two post releases on 2026-06-04, which reads like patch work at the end rather than the start of a migration path. If you are on v1.1.6 in production, the honest position is that you are maintaining a fork of your own dependencies until you move.

The WebUI and the cookbook, and what they are for

Two things in the README are easy to skim past and are worth a look before you decide anything. The first is the cookbook at runtime.agentscope.io, which the README describes as a tutorial site covering concepts, architecture, APIs and sample projects. The second is a hosted WebUI at webui.runtime.agentscope.io that the README links as an online trial. Neither requires an install, and the WebUI is the fastest way to see what the streaming and sandbox behaviour actually looks like before you commit to the dependency set.

The repository also carries examples/ with subdirectories for deployments, integrations, interrupt, modelstudio_memory and sandbox. The interrupt example is the one to open if your agent needs to pause and resume, since the README's three-stage init, query, shutdown description does not explain how a paused run is represented or where its state lives. The README is silent on that, so the example is the documentation. Read it before designing anything that needs human-in-the-loop confirmation.

Editorial conclusion

AgentScope Runtime is worth reading if you are studying how sandbox isolation, SSE streaming and multi-target deployment fit together, or if you already run v1.1.6 and need to plan a move. It is the wrong starting point for a new project: the README states that tool sandboxing, Agent-as-a-Service APIs and observability have been integrated into AgentScope 2.0 and that this repository will be archived. Before adopting anything, open the README archive notice, confirm which of the six console scripts you actually need, and check whether the AgentScope 2.0 repository covers your deployment target.

Frequently asked questions

Official sources

1. agentscope-ai/agentscope-runtime on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases