Metadata-Version: 2.5
Name: agent-sandbox-client
Version: 0.3.1a1
Summary: Agent Sandbox SDK — Create, manage, and interact with cloud sandboxes for AI agents
Project-URL: Homepage, https://github.com/alibaba-agent-sandbox/python-sdk
Project-URL: Documentation, https://github.com/alibaba-agent-sandbox/python-sdk/tree/main/docs
Project-URL: Repository, https://github.com/alibaba-agent-sandbox/python-sdk
Project-URL: Issues, https://github.com/alibaba-agent-sandbox/python-sdk/issues
Project-URL: Changelog, https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/CHANGELOG.md
Author: Anycodes
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent,ai,alibaba-cloud,cloud,sandbox
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: agent-sandbox-server==0.3.1a1
Requires-Dist: attrs>=23.2
Requires-Dist: dockerfile-parse<3,>=2.0.1
Requires-Dist: h2<5,>=4
Requires-Dist: httpcore<2,>=1.0.5
Requires-Dist: httpx[http2]<1,>=0.27
Requires-Dist: packaging>=24.1
Requires-Dist: protobuf>=5
Requires-Dist: pydantic>=2.14.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typing-extensions>=4.1
Requires-Dist: wcmatch<11,>=10.1
Requires-Dist: websockets>=16.1.1
Provides-Extra: all
Requires-Dist: filelock>=3.12; extra == 'all'
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: orjson>=3.13.0; extra == 'all'
Requires-Dist: starlette>=1.7.0; extra == 'all'
Requires-Dist: uvicorn>=0.54.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: filelock>=3.12; extra == 'dev'
Requires-Dist: mcp>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=2.4.0; extra == 'dev'
Requires-Dist: orjson>=3.13.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.17.0; extra == 'dev'
Requires-Dist: starlette>=1.7.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20260906; extra == 'dev'
Requires-Dist: uvicorn>=0.54.0; extra == 'dev'
Provides-Extra: fast
Requires-Dist: orjson>=3.13.0; extra == 'fast'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Requires-Dist: starlette>=1.7.0; extra == 'mcp'
Requires-Dist: uvicorn>=0.54.0; extra == 'mcp'
Provides-Extra: session
Requires-Dist: filelock>=3.12; extra == 'session'
Description-Content-Type: text/markdown

# agent-sandbox-client

Provider extensions use [explicit template workflows](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/template-workflows.md) ([中文](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/zh/guide/template-workflows.md)); application HTTP, stateless execution and context operations are independent.

This package is the opt-in **0.3.1a1 alpha** candidate. Use its exact PyPI version after verified publication; before that, use the [tested paired source recipe](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md). Alpha publication does not establish every provider or template as production-ready.

**Client SDK.** The product is Agent Sandbox. The import path is `agent_sandbox`. This package runs on your machine: create a sandbox, use it, and kill it. The HTTP service inside the image is [`agent-sandbox-server`](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/server-sdk/README.md). Guide: [Client SDK](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/client-sdk.md).

Template build and deploy are done by the CLI (`abx template build|deploy`).
The standard root Sandbox/AsyncSandbox and code_interpreter APIs follow Alibaba-supported E2B behavior: [migration guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/migrate-from-e2b.md) ([中文](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/zh/guide/migrate-from-e2b.md)). Provider/server/declarative extensions use the explicit ProviderSandbox entry.

This package is the `agent_sandbox` import namespace *except* `agent_sandbox.server`, which is
the container-side runtime shipped separately as
[`agent-sandbox-server`](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/server-sdk/README.md) (a hard dependency pinned to the same version,
so installing the published client also installs the matching server).

The command-line tool (`abx`) is a separate Node.js project that lives in the [`cli`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository.

## Install

```bash
python -m pip install 'agent-sandbox-client==0.3.1a1'
# Optional extras:
python -m pip install 'agent-sandbox-client[all]==0.3.1a1'
python -m pip check
```

Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated project.

## Quick start

Configure the Express API key before this example. It uses standard command and file APIs; provider-specific interpreters and registered server commands have separate requirements.

```python
import asyncio
from agent_sandbox import AsyncSandbox


async def main():
    sandbox = await AsyncSandbox.create(template="base")
    try:
        result = await sandbox.commands.run("echo hello")
        print(result.stdout)
        await sandbox.files.write("/tmp/data.txt", "content")
        print(await sandbox.files.read("/tmp/data.txt"))
    finally:
        await sandbox.kill()


asyncio.run(main())
```

Provider management operations use `agent_sandbox.providers.commands`; see the
[English guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/provider-commands.md) and
[中文指南](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/zh/guide/provider-commands.md). Writes require explicit confirmation,
and command POST requests are never automatically replayed.

## Layout

| Package | Layer |
|---------|-------|
| `agent_sandbox.transport` | L1 — HTTP/2, WebSocket, API key / AK-SK auth, config loading |
| `agent_sandbox.protocol` | L2 — envd protocol (sandbox, process, filesystem, terminal, port) |
| `agent_sandbox.api` | L3 — `Sandbox`, files, commands, code, named commands, server client |
| `agent_sandbox.declarative` | L4 — `@sandbox` decorator, `sandbox.yaml` |
| `agent_sandbox.agent` | L5 — tool schemas, MCP stdio/HTTP servers |

Run the MCP stdio server directly with `python -m agent_sandbox.agent.mcp`
(reads `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL`, `ABX_SANDBOX_DOMAIN` and `ABX_DEFAULT_TEMPLATE`).

Named-command string-array arguments (`list[str]`) preserve native JSON values. See the [server API guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/template-server-api.md#string-array-command-arguments).

## Develop

```bash
# from python-sdk/
pip install -e ./server-sdk -e "./client-sdk[dev]"
cd client-sdk && pytest -m "not integration" && ruff check src tests && mypy src/agent_sandbox
```

Licensed under Apache-2.0.
