diff --git a/.agents/README.md b/.agents/README.md index 5c9f842..23b85ba 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -252,3 +252,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ - [Unused-code cleanup](notes/implemented/process/2026-10-27-dead-code-cleanup.md) · [verification](evidence/verify/2026-10-27-dead-code-cleanup.md). - [Unused-code cleanup acceptance](evidence/verify/2026-10-27-dead-code-cleanup-acceptance.md). + +- [README audience review](notes/proposed/process/2026-10-28-readme-audience-review.md) · [verification](evidence/verify/2026-10-28-readme-audience-review.md). diff --git a/.agents/evidence/verify/2026-10-28-readme-audience-review.md b/.agents/evidence/verify/2026-10-28-readme-audience-review.md new file mode 100644 index 0000000..56c7480 --- /dev/null +++ b/.agents/evidence/verify/2026-10-28-readme-audience-review.md @@ -0,0 +1,44 @@ +# Verification: python-sdk README audience review + +- Date: 2026-10-28 +- Result: PASS — scoped local documentation verification. Remote checks and merge are reported separately on the PR. +- Base revision: `9fdeef5adeb22f64375ee29d04b54b206686347a`. +- Scope: `README.md`, `README.zh-CN.md`; repository-owned note and this evidence. +- Environment: Linux, Node.js 22.22.2, system Python 3.13.13; SDK/server and checker environment Python 3.11.15. + +## What was reviewed + +The opening mixed standard clients, provider internals, server packaging, migration and build details. A large architecture diagram and repeated documentation indexes obscured which Python client a reader should import. + +Lead with Python use cases, installation and one interpreter example with deletion in finally. Explain Sandbox, AsyncSandbox, code_interpreter and ProviderSandbox in a small selection table. Link provider/template, server, authentication and migration guides. Keep client/server package ownership visible without namespace implementation details. + +## Validation + +`python "$README_AUDIT"` passed for 6 changed Markdown files, with zero failures. This temporary audit used the existing template repository's Markdown-target/heading parser at its checked-out base revision and a task wrapper (SHA-256 `fe8c34fd4ef2474ca7dfcfcc94d2a055e9ead01a92fe2695446cfe08341df7e6`). It checks changed local targets/fragments, incoming active README heading links, one H1 and reciprocal language links in each root README, balanced fences and Python snippet syntax. `README_AUDIT` denotes that temporary wrapper; no machine-local path is part of the repository. It does not validate cloud runtime behavior. + +`git -c core.filemode=false diff --check HEAD` passed. The filesystem exposes executable bits on unchanged checkout files; ignoring those bits for task-local Git commands avoided including unrelated mode changes. The staged change was reviewed for prose-only scope, translation equivalence, current command/API names and preserved license links. Package registry checks on 2026-10-28 found CLI 0.5.8 and Python client 0.4.0a6; the Node SDK public npm metadata endpoint returned HTTP 404. No new package publication is claimed. + +## Limits and cleanup + +Documentation changes only. No provider API calls, sandboxes, templates, cloud keys, model calls, deployments or package releases were created by local verification. Existing historical receipts remain unchanged. CI and existing main-branch publication workflows retain their own scope. + +## Repository checks + +- `bash scripts/check-repo-health.sh`: PASS: 106 checks, 0 failures; 1 warning. +- `make hygiene`: PASS. +- `make test`: PARTIAL: server suite 872 passed, 1 skipped, 3 failed; make stopped before client suite. +- `pytest (three failed server tests after installing missing pip in the test environment)`: PARTIAL: package-list test now passes; malformed WebSocket and chunked-request tests still receive HTTP 501/502 instead of 400. +- `pytest tests/ (client-sdk)`: PASS: 2348 passed, 27 skipped. +- `make lint typecheck`: PASS: Ruff checks passed for both packages; mypy passed for 56 server and 101 client source files (one unused-section configuration note). + +## Reviewed public-file identity + +| File | SHA-256 | +| --- | --- | +| `CHANGELOG.md` | `f412ce3f97945f2bf7ea93da3b5cc1a05844a937cd2da362054228df5d408a66` | +| `README.md` | `fafd9d8ccf215f639cad22d099670e2be2063f430c09b0b2b8da7af2dd5ca584` | +| `README.zh-CN.md` | `2983f3a8cab891379e1a5f6ae60928f92ab9f7fd6b07b6f6626e95e9ee97ea76` | + +## Final local review follow-up + +The two raw HTTP server tests still fail locally with HTTP 501/502 instead of 400 after the missing-pip prerequisite was fixed. Their executable source is unchanged by this documentation PR. The reason for those responses is not established. The PR must pass the complete current-head remote matrix before merge; no local server-suite pass is claimed. The changelog entry was folded into the existing Unreleased/Changed group during review. diff --git a/.agents/notes/proposed/process/2026-10-28-readme-audience-review.md b/.agents/notes/proposed/process/2026-10-28-readme-audience-review.md new file mode 100644 index 0000000..4247e35 --- /dev/null +++ b/.agents/notes/proposed/process/2026-10-28-readme-audience-review.md @@ -0,0 +1,46 @@ +# Decision: Make the python-sdk README a reader entry point + +Status: proposed + +## Problem + +The opening mixed standard clients, provider internals, server packaging, migration and build details. A large architecture diagram and repeated documentation indexes obscured which Python client a reader should import. + +## Decision + +Lead with Python use cases, installation and one interpreter example with deletion in finally. Explain Sandbox, AsyncSandbox, code_interpreter and ProviderSandbox in a small selection table. Link provider/template, server, authentication and migration guides. Keep client/server package ownership visible without namespace implementation details. + +A README answers what this repository provides, who it serves, how to start, where to continue, how to contribute and what license applies where established. Detailed migration is a secondary guide, not the project introduction. Public usage stays separate from engineering acceptance and delivery history. + +Scoped public files: `README.md`, `README.zh-CN.md`. + +## API Design + +N/A — this decision does not involve API changes. All executable behavior and public exports remain unchanged. + +## Alternatives considered + +- Only remove the migration heading: leaves each repository's audience and navigation problems unresolved. +- Use one identical README template everywhere: obscures the different needs of library users, catalog users, site contributors and article authors. +- Delete detailed material: useful reference and maintainer instructions should remain available through their owning guides and historical records. + +## Dependencies + +Existing guides, actual package/source metadata and the owning repositories linked with absolute GitHub URLs. No new runtime dependencies, release, build contract or cloud permissions. + +## Test Strategy + +Check changed Markdown links and anchors, incoming active links to root README headings, reciprocal language links, fenced Python syntax and the final scoped diff. Run repository documentation/record checks and applicable CI. Review examples against current source and package availability. No cloud mutation or real-model run is needed to validate this prose-only change; document checks do not establish runtime acceptance. + +## Acceptance criteria + +- The first screen identifies this repository's purpose and primary next action. +- Installation and examples match actual package scope and current source behavior. +- English and Chinese READMEs provide equivalent tasks and links. +- Migration, internal implementation and dated acceptance reports do not dominate the introduction. +- Detailed reference and maintainer material remains reachable. +- Local documentation checks and current-head required CI/review results are recorded honestly. + +## Evidence + +[Verification](../../../evidence/verify/2026-10-28-readme-audience-review.md). diff --git a/CHANGELOG.md b/CHANGELOG.md index d9c229b..aab1914 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ### Changed +- Reorganize the English and Chinese repository READMEs around installation, first use and task-oriented documentation; keep migration and detailed reference material in their guides. + - Remove an uncalled private configuration alias helper while preserving public configuration schema exports and compatibility signatures. - Normalize Python MCP background-task `sandbox_id` handles to the actual `provider:id`. Return the opaque handle unchanged when querying/cancelling; callers parsing a raw ID must update. Legacy raw IDs still resolve within a unique lifecycle cache or the SDK's default-provider scope. / Python MCP 后台任务的 `sandbox_id` 句柄规范为实际 `provider:id`；查询和取消须原样回传，拆分原始 ID 的调用者需要更新。历史原始 ID 仍可在无歧义的生命周期缓存或 SDK 默认提供方范围内解析。 diff --git a/README.md b/README.md index 563c552..ca2c85d 100644 --- a/README.md +++ b/README.md @@ -1,237 +1,88 @@ -# Agent Sandbox - -[Launch templates](docs/en/guide/template-workflows.md): start the complete template and access all declared services. +# Agent Sandbox Python SDK **English** | [中文](README.zh-CN.md) -[Standard E2B migration contract](docs/en/guide/migrate-from-e2b.md) - - -[![CI](https://github.com/alibaba-agent-sandbox/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/alibaba-agent-sandbox/python-sdk/actions/workflows/ci.yml) -[![License](https://img.shields.io/github/license/agent-sandbox/python-sdk)](LICENSE) - -> Cloud sandboxes for AI agents — create, execute, and manage isolated environments in seconds. - -**Agent Sandbox** is a Python SDK for sandboxes. The default provider is Alibaba Cloud Express (`alicloud-express`, Function Compute). OpenSandbox, the container edition, CubeSandbox, and E2B are catalog `node` plugins in `awesome-providers` (`provider.mjs`). Install one with `abx provider install alibaba-agent-sandbox/awesome-providers// --allow-unpinned --yes` (or `python -m agent_sandbox.providers install registry: --yes`). After that, both `abx --provider ` and `ProviderSandbox.create(provider="")` use it. The Python SDK reaches a `node` provider through the local engine (`abx provider engine serve`; `abx` on `PATH` or `ABX_BIN`). The CLI loads Express plus installed `node`, `exec` and `rest` plugins. It is the -standard sync/async runtime and Template client. Project provider/server template launches use -`abx template launch ` from the CLI; advanced image preparation uses -`abx template build|deploy`. The SDK uses E2B-shaped method names so that E2B code -ports with few changes; the standard API follows Alibaba-supported E2B behavior (see [Migrate from E2B](docs/en/guide/migrate-from-e2b.md)). - -This repository (`python-sdk`) contains the **Python SDK**, packaged as two lock-step distributions. The `abx` command-line tool is a separate Node.js project that lives in the -[`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository (see [Related: the abx CLI](#related-the-abx-cli)). - -| Folder | Distribution | Import path | Purpose | -|--------|-------------------|-------------|---------| -| [`client-sdk/`](client-sdk/) | `agent-sandbox-client` | `agent_sandbox` | Sync/async client SDK: `Sandbox`, `AsyncSandbox`, `ProviderSandbox`, files, commands, code interpreter, named commands, declarative `@sandbox`, Agents API client, MCP server, E2B migration helper | -| [`server-sdk/`](server-sdk/) | `agent-sandbox-server` | `agent_sandbox.server` | Container-side runtime: the persistent HTTP service (default port 9000) that runs *inside* a sandbox image | - -Both distributions share the `agent_sandbox` namespace (the client owns `agent_sandbox/__init__.py`, -the server only ships `agent_sandbox/server/`) and are **versioned in lockstep** with the same version number. - -**Client SDK** runs on your machine: create a sandbox and use it. Guide: [Client SDK](docs/en/guide/client-sdk.md). Examples: `examples/quickstart/`, `examples/compat-demos/`, `examples/agents/`, `examples/scenarios/`. - -**Server SDK** runs inside the sandbox image: the HTTP service the image starts. Guide: [Server SDK](docs/en/guide/server-sdk.md). Examples: `examples/templates/python-hello/commands.py`, `examples/templates/agents-cli/commands.py`. - -## Sites - -| Site | URL | -|---|---| -| Official site | https://www.agent-sandbox.cn | -| Provider registry | https://registry.agent-sandbox.cn | - -The installer fetches the catalog index at `https://registry.agent-sandbox.cn/providers/index.json`. `ABX_PROVIDER_REGISTRY` overrides that URL. - ---- - -Provider management operations are available through `agent_sandbox.providers.commands`; see the [provider command guide](docs/en/guide/provider-commands.md). - -## Client SDK - -- **Sync and async standard clients** — `Sandbox.create()` and `AsyncSandbox.create()`, shell execution, code interpretation, file I/O, port forwarding, and WebSocket streaming. -- **Explicit execution entry points** — process execution, the standard interpreter client, and template application commands have separate runtime requirements (see Execution API below). -- **MCP server** — expose sandbox operations as MCP tools for LLM agents. -- **Declarative decorator** — `@sandbox` turns a plain function into a remote sandbox execution with automatic serialisation. -- **Standard sync/async clients** — `agent_sandbox` exports the standard Sandbox and AsyncSandbox; see [Migrate from E2B](docs/en/guide/migrate-from-e2b.md). +[![CI](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/workflows/ci.yml) -## Server SDK +Create sandboxes, execute code and commands, and work with remote files from Python. This repository contains the client SDK and the runtime used inside sandbox application images. -- **In-image HTTP service** — `commands.py` imports `agent_sandbox.server` and calls `start(9000)`. -- **Registered commands** — `@command` functions become routes the Client SDK calls with `sandbox.run`. -- **Agents API** — Codex and Qwen Code HTTP sessions inside the sandbox. Install a CLI when you call it. Guide: [Agents API](docs/en/guide/agents-api.md). -- **Templates** — start the complete template with `abx template launch `; use `template build` / `template deploy` for advanced image preparation. +[Website](https://www.agent-sandbox.cn/en/) · [Documentation](docs/en/README.md) · [Examples](examples/README.md) ## Installation -Use Python 3.10 or newer in a virtual environment. The client installs its matching server dependency automatically. See the [installation guide](docs/en/guide/install-python.md) for a pinned version, optional extras and development setup. +Use Python 3.10+ in a virtual environment: ```bash python -m pip install --index-url https://pypi.org/simple --upgrade --pre agent-sandbox-client python -m pip check ``` -`--pre` opts into alpha releases. The command-line tool is installed separately: see [the abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox). +`--pre` opts into preview releases. The package imports as `agent_sandbox` and installs its matching `agent-sandbox-server` dependency. See [installation](docs/en/guide/install-python.md) for a pinned version, optional extras and source setup. The PyPI name `agent-sandbox` belongs to a different project. -Do not run `pip install agent-sandbox`; that PyPI name belongs to an unrelated project. +## Quick start -## Quick Start - -Configure `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL`, `ABX_SANDBOX_DOMAIN`. Replace E2B imports as described in the [migration guide](docs/en/guide/migrate-from-e2b.md). +Configure your Express Sandbox API key, API URL and sandbox domain using `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL` and `ABX_SANDBOX_DOMAIN`. Use values for the same account and region; see [authentication](docs/en/guide/authentication.md) and [permissions](docs/en/guide/permissions.md) for their source and setup. ```python from agent_sandbox.code_interpreter import Sandbox sandbox = Sandbox.create(template="code-interpreter-v1") try: - print(sandbox.commands.run("printf hello").stdout) + sandbox.files.write("/tmp/input.txt", "hello") + print(sandbox.commands.run("cat /tmp/input.txt").stdout) print(sandbox.run_code("1 + 1").text) finally: sandbox.kill() ``` -## Provider and server extensions - -Set `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL` and `ABX_SANDBOX_DOMAIN`, then create a native instance and execute a process with `ProviderSandbox`: - -```python -import asyncio -from agent_sandbox import ProviderSandbox - -async def main(): - sandbox = await ProviderSandbox.create(template="base", provider="alicloud-express") - try: - result = await sandbox.commands.run("python3 -c 'print(2 ** 10)'") - print(result.stdout) # 1024 - finally: - try: - await sandbox.kill() - finally: - await sandbox.close() - -asyncio.run(main()) -``` - -This `python3` invocation is a process, not a persistent interpreter. Interpreter operations absent from a provider return `E8004`; the standard `code_interpreter.Sandbox` above is a separate entry point. `close()` releases client connections; `kill()` deletes the instance. +This example needs an interpreter-enabled template. `kill()` deletes the sandbox when the work finishes, including on failure. -## Execution API +## Choose a client -| Entry point | Purpose | Requirement | -|---|---|---| -| `ProviderSandbox.commands.run()` | Execute a process and read stdout, stderr and exit code | Provider implements process operations | -| Standard `code_interpreter.Sandbox.run_code()` | Execute interpreter code | A matching native runtime such as `code-interpreter-v1` | -| `ProviderSandbox.application_client()` | Call application commands registered by a template HTTP service | Start the template service and supply the correct port and application token | +| Entry point | Use it for | +| --- | --- | +| `from agent_sandbox import Sandbox, AsyncSandbox` | Synchronous or asynchronous Express lifecycle, commands and files | +| `from agent_sandbox.code_interpreter import Sandbox, AsyncSandbox` | Code execution with persistent interpreter contexts | +| `from agent_sandbox import ProviderSandbox` | Asynchronous provider plugins and template application services | -Named application commands are registered by the in-sandbox server. Follow [template startup](docs/en/guide/template-workflows.md) to create or connect to that application, preserving provider gateway headers, URL prefixes and query parameters; do not assume `base` registers `hello`. See [Providers](docs/en/guide/providers.md) for cross-language plugin execution. +Use `await` with `AsyncSandbox` and `ProviderSandbox`. Provider operations and interpreter availability depend on the selected backend and template; see [SDK usage](docs/en/guide/sdk-usage.md). -## Templates +## Other providers and application templates -Official and community templates live in the -[`alibaba-agent-sandbox/awesome-templates`](https://github.com/alibaba-agent-sandbox/awesome-templates) -repository — the single source of truth for template content, the index, and -publishing. The index is consumed by the `abx template search|install` commands -([Related: the abx CLI](#related-the-abx-cli)); the `template.yaml` contract that -templates follow is defined in the [Template YAML Spec](docs/en/reference/template-yaml-spec.md). +Express is built in. Installable [provider plugins](https://github.com/Alibaba-Agent-Sandbox/awesome-providers) connect `ProviderSandbox` to other backends. Follow [provider setup](docs/en/guide/providers.md) before using one. -[`examples/templates/`](examples/templates/) only keeps a minimal -`python-hello` **fixture** for offline tests — it is not a publishing source. -See [examples/templates/README.md](examples/templates/README.md) for the -fixture contract and index behaviour (caching, offline fallback, pinned refs). +Application templates package browser tools, coding agents and other services. Launch a template with the [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox), then use its returned sandbox ID and the [template startup guide](docs/en/guide/template-workflows.md) to connect from Python. Named application commands require that service to be running. -## Architecture +## In-sandbox runtime -```mermaid -graph TB - L5["L5 Agent — MCP server, Agents API client"] - L4["L4 Declarative — @sandbox decorator"] - L3["L3 API — Sandbox, Files, Code, Commands"] - L2["L2 Protocol — envd REST + WebSocket"] - L1["L1 Transport — HTTP/2, API Key, envd token"] - GW["Alibaba Cloud FC"] - - L5 --> L4 --> L3 --> L2 --> L1 --> GW -``` +| Package | Runs where | Guide | +| --- | --- | --- | +| [`agent-sandbox-client`](client-sdk/) | Your application | [Client SDK](docs/en/guide/client-sdk.md) | +| [`agent-sandbox-server`](server-sdk/) | Inside a sandbox image | [Server SDK](docs/en/guide/server-sdk.md) | -Lower layers never import upper layers. Full design: [`docs/en/design/architecture.md`](docs/en/design/architecture.md). +The server exposes registered application commands over HTTP. Template authors install the server in their images and define the service startup. Client and server packages share a version; see the [server API guide](docs/en/guide/template-server-api.md) for command registration and authentication. ## Documentation -> Full documentation index: [`docs/README.md`](docs/README.md) (bilingual navigation) - -### Tutorials & Guides - -| Guide | Link | -|-------|------| -| Getting Started | [Getting Started](docs/en/guide/getting-started.md) | -| Best Practices | [Best Practices](docs/en/guide/best-practices.md) | -| Accessibility | [Accessibility](ACCESSIBILITY.md) | -| File and command controls | [File and command controls](docs/en/guide/file-and-command-controls.md) | -| Hosted agents | [Hosted agents](docs/en/guide/hosted-agents.md) | -| SDK Usage | [SDK Usage](docs/en/guide/sdk-usage.md) | -| Authentication | [Authentication](docs/en/guide/authentication.md) | -| Environment Variables | [Environment Variables](docs/en/guide/environment-variables.md) | -| Authoring Templates | [Authoring Templates](docs/en/guide/authoring-templates.md) | -| Build & Deploy (CLI) | [Build & Deploy](docs/en/guide/build-and-deploy.md) | -| Declarative Usage | [Declarative Usage](docs/en/guide/declarative-usage.md) | -| Binary MCP files | [Upload/download](docs/en/guide/mcp-binary-files.md) | -| Background MCP tasks | [Reconnectable tasks](docs/en/guide/mcp-background-tasks.md) | -| MCP Integration | [MCP Integration](docs/en/guide/mcp-integration.md) | -| Session Persistence | [Session Persistence](docs/en/guide/session-persistence.md) | -| Migrate from E2B | [Migrate from E2B](docs/en/guide/migrate-from-e2b.md) | -| Troubleshooting | [Troubleshooting](docs/en/guide/troubleshooting.md) | - -### Reference - -| Document | Link | -|----------|------| -| API Reference | [API Reference](docs/en/reference/api-reference.md) | -| Configuration | [Configuration](docs/en/reference/configuration.md) | -| Error Codes | [Error Codes](docs/en/reference/error-codes.md) | -| Template YAML Spec | [Template YAML Spec](docs/en/reference/template-yaml-spec.md) | - -### Design & Architecture - -| Document | Link | -|----------|------| -| Design Index | [Design Index](docs/en/DESIGN.md) | -| Architecture | [Architecture](docs/en/design/architecture.md) | -| SDK API Design | [SDK API Design](docs/en/design/sdk-api-design.md) | -| Template System | [Template System](docs/en/design/template-system.md) | - -### Other Resources - -| Resource | Link | -|----------|------| -| Changelog | [CHANGELOG.md](CHANGELOG.md) | -| Contributing Guide | [CONTRIBUTING.md](.github/CONTRIBUTING.md) | -| License | [Apache-2.0](LICENSE) | -| Examples | [examples/](examples/) | -| SDK skill | [agent-sandbox-sdk/SKILL.md](agent-sandbox-sdk/SKILL.md) — how an agent writes a client and a template | +| Task | Guide | +| --- | --- | +| Make your first API calls | [Getting started](docs/en/guide/getting-started.md) | +| Look up methods and models | [API reference](docs/en/reference/api-reference.md) | +| Configure credentials and endpoints | [Authentication](docs/en/guide/authentication.md) | +| Configure file and process behavior | [File and command controls](docs/en/guide/file-and-command-controls.md) | +| Move existing E2B code | [Migration guide](docs/en/guide/migrate-from-e2b.md) | +| Resolve errors | [Troubleshooting](docs/en/guide/troubleshooting.md) | -## Related: the abx CLI - -The `abx` command-line tool (`@agent-sandbox/cli`, Node.js) is developed in the -[`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository. It shares sandboxes, templates and -credentials with this SDK. Its installation, command reference, tutorials, MCP server -commands and the Agent Skill (`SKILL.md`) are documented there: +See the [full documentation index](docs/README.md), [examples](examples/README.md) and [changelog](CHANGELOG.md). -- [CLI README](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/README.md) — installation ([CLI binary installation](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/binary-installation.md)) -- [CLI Tutorial](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/guide/cli-tutorial.md) · [CLI Reference](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/reference/cli-reference.md) -- [Agent Skill Installation & Distribution](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/guide/agent-skill-installation.md) +## Related: the abx CLI -Named commands support native `list[str]` JSON arguments. See the [server API guide](docs/en/guide/template-server-api.md#string-array-command-arguments) for validation and server compatibility. +The [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox) provides terminal operations, template builds and launches. Install it separately when your workflow requires it. ## Contributing -We welcome contributions! Please read the [Contributing Guide](.github/CONTRIBUTING.md) to get started. +See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for the development environment and checks for both packages. Report SDK and runtime issues in [this repository](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues). ## License -[Apache-2.0](LICENSE) — see [`NOTICE`](NOTICE) for copyright information. - -[Builtin runtime architecture and Python engine migration](docs/en/design/builtin-data-plane.md). - -Provider-owned pause/resume and Snapshot commands share one implementation across CLI and SDK; see the [registration and usage guide](docs/en/guide/provider-commands.md). - -Current API / 当前接口: [development contract](docs/en/guide/current-api.md). - -[Express authentication and required permissions](docs/en/guide/permissions.md): existing API key or explicitly confirmed AK/SK-managed key. +[Apache-2.0](LICENSE). See [NOTICE](NOTICE) for attribution. diff --git a/README.zh-CN.md b/README.zh-CN.md index 3dde782..b4a07eb 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,231 +1,88 @@ -# Agent Sandbox +# Agent Sandbox Python SDK -[模板启动](docs/zh/guide/template-workflows.md)：整体启动模板并访问全部声明服务。 +**中文** | [English](README.md) -[English](README.md) | **中文** +[![CI](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/workflows/ci.yml) -[标准 E2B 迁移契约](docs/zh/guide/migrate-from-e2b.md) +在 Python 中创建沙箱、执行代码和命令，以及操作远程文件。本仓库包含客户端 SDK 和在沙箱应用镜像内运行的服务端运行时。 - -[![CI](https://github.com/alibaba-agent-sandbox/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/alibaba-agent-sandbox/python-sdk/actions/workflows/ci.yml) -[![License](https://img.shields.io/github/license/agent-sandbox/python-sdk)](LICENSE) - -> 为 AI Agent 打造的云沙箱 —— 秒级创建、执行、管理隔离环境。 - -**Agent Sandbox** 是沙箱的 Python SDK。默认提供方是阿里云极速版（`alicloud-express`，函数计算）。OpenSandbox、容器版、CubeSandbox 和 E2B 都是 `awesome-providers` 里的目录 `node` 插件（`provider.mjs`）。用 `abx provider install alibaba-agent-sandbox/awesome-providers// --allow-unpinned --yes`（或 `python -m agent_sandbox.providers install registry: --yes`）安装。装好之后，`abx --provider ` 和 `ProviderSandbox.create(provider="")` 都能用。Python SDK 通过本机引擎（`abx provider engine serve`；`abx` 在 `PATH` 里或由 `ABX_BIN` 指定）使用 `node` 提供方。CLI 加载极速版，以及已安装的 `node`、`exec` 和 `rest` 插件。标准接口包含同步／异步运行时和 Template 客户端；项目 Provider／Server 模板通过 CLI 的 `abx template launch ` 统一启动，高级镜像准备使用 `abx template build|deploy`。SDK 的方法名参考了 E2B， -方便 E2B 代码迁移，标准接口遵循阿里云支持版本的行为契约（见[从 E2B 迁移](docs/zh/guide/migrate-from-e2b.md)）。 - -本仓库（`python-sdk`）包含 **Python SDK**，以两个版本同步的分发包提供。命令行工具 `abx` 是独立的 -Node.js 项目，位于 [`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库（见[相关：abx CLI](#相关abx-cli)）。 - -| 目录 | PyPI 分发包 | 导入路径 | 用途 | -|------|-------------|----------|------| -| [`client-sdk/`](client-sdk/) | `agent-sandbox-client` | `agent_sandbox` | 同步/异步客户端 SDK：`Sandbox`、`AsyncSandbox`、`ProviderSandbox`、文件、命令、代码解释器、命名命令、声明式 `@sandbox`、Agents API 客户端、MCP Server、E2B 迁移辅助 | -| [`server-sdk/`](server-sdk/) | `agent-sandbox-server` | `agent_sandbox.server` | 容器侧运行时：运行在沙箱镜像*内部*的常驻 HTTP 服务（默认端口 9000） | - -两个分发包共享 `agent_sandbox` 命名空间（client 提供 `agent_sandbox/__init__.py`，server 只包含 -`agent_sandbox/server/`），并以相同版本号**同步发布**。 - -**Client SDK** 跑在你的机器上：创建沙箱并使用它。说明见 [Client SDK](docs/zh/guide/client-sdk.md)。示例在 `examples/quickstart/`、`examples/compat-demos/`、`examples/agents/`、`examples/scenarios/`。 - -**Server SDK** 跑在沙箱镜像里面：镜像启动的 HTTP 服务。说明见 [Server SDK](docs/zh/guide/server-sdk.md)。示例是 `examples/templates/python-hello/commands.py` 和 `examples/templates/agents-cli/commands.py`。 - -## 网站 - -| 网站 | 地址 | -|---|---| -| 官网 | https://www.agent-sandbox.cn | -| 提供方注册站 | https://registry.agent-sandbox.cn | - -安装器拉取的目录索引是 `https://registry.agent-sandbox.cn/providers/index.json`。`ABX_PROVIDER_REGISTRY` 可以改这个地址。 - ---- - -提供方管理操作通过 `agent_sandbox.providers.commands` 调用，参阅[提供方命令指南](docs/zh/guide/provider-commands.md)。 - -## Client SDK - -- **同步与异步标准客户端** —— `Sandbox.create()` 与 `AsyncSandbox.create()`，Shell 执行、代码解释、文件读写、端口转发与 WebSocket 流；Provider／Server 扩展使用异步 `ProviderSandbox`。 -- **明确的执行入口** —— 进程执行、标准解释器客户端、模板应用命令各有对应的运行时要求（见下方执行 API）。 -- **MCP Server** —— 将沙箱操作暴露为 MCP 工具，供 LLM Agent 调用。 -- **声明式装饰器** —— `@sandbox` 将普通函数变为远程沙箱执行，自动序列化。 -- **标准同步与异步客户端** —— `agent_sandbox` 导出标准 Sandbox 与 AsyncSandbox，见[从 E2B 迁移](docs/zh/guide/migrate-from-e2b.md)。 - -## Server SDK - -- **镜像内 HTTP 服务** —— `commands.py` 导入 `agent_sandbox.server` 并调用 `start(9000)`。 -- **注册命令** —— `@command` 函数变成路由，Client SDK 用 `sandbox.run` 调用。 -- **Agents API** —— 沙箱里的 Codex 与 Qwen Code HTTP 会话。CLI 按需安装。说明见 [Agents API](docs/zh/guide/agents-api.md)。 -- **模板** —— 使用 `abx template launch ` 启动完整模板；高级镜像准备使用 `template build` / `template deploy`。 +[官网](https://www.agent-sandbox.cn) · [使用文档](docs/zh/README.md) · [示例](examples/README.zh-CN.md) ## 安装 -使用 Python 3.10 或更高版本及虚拟环境。客户端会自动安装同版本的服务端依赖。固定版本、可选依赖及开发安装见[安装指南](docs/zh/guide/install-python.md)。 +需要 Python 3.10+，建议使用虚拟环境： ```bash python -m pip install --index-url https://pypi.org/simple --upgrade --pre agent-sandbox-client python -m pip check ``` -`--pre` 表示选择 alpha 预发布版本。命令行工具独立安装，见 [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox)。 - -不要执行 `pip install agent-sandbox`；该 PyPI 名称属于另一个无关项目。 +`--pre` 表示选择预览版本。导入名为 `agent_sandbox`，安装时自动带上同版本的 `agent-sandbox-server` 依赖。固定版本、可选依赖和源码安装见[安装指南](docs/zh/guide/install-python.md)。PyPI 上的 `agent-sandbox` 属于另一个项目。 ## 快速开始 -配置 `ABX_SANDBOX_API_KEY`、`ABX_SANDBOX_BASE_URL`、`ABX_SANDBOX_DOMAIN`，按[迁移指南](docs/zh/guide/migrate-from-e2b.md)替换 E2B 导入。 +通过 `ABX_SANDBOX_API_KEY`、`ABX_SANDBOX_BASE_URL` 和 `ABX_SANDBOX_DOMAIN` 配置极速版的 Sandbox API Key、API 地址和沙箱域名。三者应属于同一账号与地域；来源和配置方法见[认证指南](docs/zh/guide/authentication.md)与[权限指南](docs/zh/guide/permissions.md)。 ```python from agent_sandbox.code_interpreter import Sandbox sandbox = Sandbox.create(template="code-interpreter-v1") try: - print(sandbox.commands.run("printf hello").stdout) + sandbox.files.write("/tmp/input.txt", "hello") + print(sandbox.commands.run("cat /tmp/input.txt").stdout) print(sandbox.run_code("1 + 1").text) finally: sandbox.kill() ``` -## Provider 与 Server 扩展 +示例需要支持解释器的模板。工作结束或发生异常时，`kill()` 都会删除沙箱。 -设置 `ABX_SANDBOX_API_KEY`、`ABX_SANDBOX_BASE_URL` 和 `ABX_SANDBOX_DOMAIN` 后，使用 `ProviderSandbox` 创建原生实例并执行进程： - -```python -import asyncio -from agent_sandbox import ProviderSandbox - -async def main(): - sandbox = await ProviderSandbox.create(template="base", provider="alicloud-express") - try: - result = await sandbox.commands.run("python3 -c 'print(2 ** 10)'") - print(result.stdout) # 1024 - finally: - try: - await sandbox.kill() - finally: - await sandbox.close() - -asyncio.run(main()) -``` +## 选择客户端 -这里的 `python3` 是一次进程执行，不是持久代码解释器。Provider 未实现的解释器操作会返回 `E8004`；上方标准 `code_interpreter.Sandbox` 是独立入口。`close()` 只关闭客户端连接，删除实例使用 `kill()`。 +| 入口 | 用途 | +| --- | --- | +| `from agent_sandbox import Sandbox, AsyncSandbox` | 同步或异步使用极速版的沙箱生命周期、命令和文件操作 | +| `from agent_sandbox.code_interpreter import Sandbox, AsyncSandbox` | 在持久解释器上下文中执行代码 | +| `from agent_sandbox import ProviderSandbox` | 异步使用提供方插件和模板应用服务 | -## 执行 API +`AsyncSandbox` 和 `ProviderSandbox` 使用 `await`。提供方操作和解释器是否可用取决于所选后端与模板，详见 [SDK 用法](docs/zh/guide/sdk-usage.md)。 -| 入口 | 用途 | 前提 | -|---|---|---| -| `ProviderSandbox.commands.run()` | 执行进程，读取 stdout、stderr 和退出码 | Provider 实现进程操作 | -| 标准 `code_interpreter.Sandbox.run_code()` | 执行解释器代码 | 使用 `code-interpreter-v1` 等对应原生运行时 | -| `ProviderSandbox.application_client()` | 调用模板 HTTP 服务注册的应用命令 | 先启动模板服务，传入正确端口与应用令牌 | +## 其他提供方与应用模板 -命名应用命令由沙箱内服务端注册。通过 [模板启动](docs/zh/guide/template-workflows.md) 创建或连接对应应用，保留 Provider 返回的网关请求头、URL 前缀和查询参数；不要假定 `base` 注册了 `hello`。Provider 插件的跨语言执行方式见 [Provider 指南](docs/zh/guide/providers.md)。 +极速版为内置后端。[提供方插件](https://github.com/Alibaba-Agent-Sandbox/awesome-providers)可让 `ProviderSandbox` 连接其他后端，使用前按[提供方指南](docs/zh/guide/providers.md)完成安装与配置。 -## 模板 +应用模板封装浏览器工具、编码 Agent 等服务。先用 [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox)启动模板，再根据返回的沙箱 ID 和[模板启动指南](docs/zh/guide/template-workflows.md)从 Python 连接。调用命名应用命令前，需要先启动对应服务。 -官方与社区模板统一维护在 -[`alibaba-agent-sandbox/awesome-templates`](https://github.com/alibaba-agent-sandbox/awesome-templates) -仓库——模板内容、索引与发布的唯一真源。该索引由 `abx template search|install` 命令使用 -（见[相关：abx CLI](#相关abx-cli)）；模板遵循的 `template.yaml` 契约见 -[Template YAML 规范](docs/zh/reference/template-yaml-spec.md)。 +## 沙箱内运行时 -[`examples/templates/`](examples/templates/) 仅保留一个最小的 `python-hello` -**测试夹具（fixture）**用于离线测试，并非模板发布真源。夹具契约与索引行为 -（缓存、离线回退、锁定版本）详见 [examples/templates/README.md](examples/templates/README.md)。 +| 包 | 运行位置 | 指南 | +| --- | --- | --- | +| [`agent-sandbox-client`](client-sdk/) | 用户的应用中 | [客户端 SDK](docs/zh/guide/client-sdk.md) | +| [`agent-sandbox-server`](server-sdk/) | 沙箱镜像内 | [服务端 SDK](docs/zh/guide/server-sdk.md) | -## 架构 - -```mermaid -graph TB - L5["L5 Agent — MCP Server、Agents API 客户端"] - L4["L4 Declarative — @sandbox 装饰器"] - L3["L3 API — Sandbox、Files、Code、Commands"] - L2["L2 Protocol — envd REST + WebSocket"] - L1["L1 Transport — HTTP/2、API Key、envd token"] - GW["阿里云函数计算 FC"] - - L5 --> L4 --> L3 --> L2 --> L1 --> GW -``` - -低层不引用高层。完整设计文档：[`docs/zh/design/architecture.md`](docs/zh/design/architecture.md)。 +服务端通过 HTTP 暴露已注册的应用命令。模板作者在镜像内安装服务端并定义启动方式。客户端与服务端使用同一版本；命令注册与认证见[服务端 API 指南](docs/zh/guide/template-server-api.md)。 ## 文档 -> 完整文档索引：[`docs/README.md`](docs/README.md)（双语导航） - -### 教程与指南 - -| 指南 | 链接 | -|------|------| -| 快速入门 | [快速入门](docs/zh/guide/getting-started.md) | -| 最佳实践 | [最佳实践](docs/zh/guide/best-practices.md) | -| 无障碍 | [无障碍说明](ACCESSIBILITY.md) | -| 文件与命令控制 | [文件与命令控制](docs/zh/guide/file-and-command-controls.md) | -| 托管代理 | [托管代理](docs/zh/guide/hosted-agents.md) | -| SDK 使用 | [SDK 使用](docs/zh/guide/sdk-usage.md) | -| 认证配置 | [认证配置](docs/zh/guide/authentication.md) | -| 环境变量 | [环境变量](docs/zh/guide/environment-variables.md) | -| 编写模板 | [编写模板](docs/zh/guide/authoring-templates.md) | -| 构建与部署（CLI） | [构建与部署](docs/zh/guide/build-and-deploy.md) | -| 声明式用法 | [声明式用法](docs/zh/guide/declarative-usage.md) | -| MCP 后台任务 | [可重连任务](docs/zh/guide/mcp-background-tasks.md) | -| MCP 二进制文件 | [上传/下载](docs/zh/guide/mcp-binary-files.md) | -| MCP 集成 | [MCP 集成](docs/zh/guide/mcp-integration.md) | -| 会话持久化 | [会话持久化](docs/zh/guide/session-persistence.md) | -| 从 E2B 迁移 | [从 E2B 迁移](docs/zh/guide/migrate-from-e2b.md) | -| 故障排查 | [故障排查](docs/zh/guide/troubleshooting.md) | - -### 参考手册 - -| 文档 | 链接 | -|------|------| -| API 参考 | [API 参考](docs/zh/reference/api-reference.md) | -| 配置说明 | [配置说明](docs/zh/reference/configuration.md) | -| 错误码 | [错误码](docs/zh/reference/error-codes.md) | -| Template YAML 规范 | [Template YAML 规范](docs/zh/reference/template-yaml-spec.md) | - -### 设计与架构 - -| 文档 | 链接 | -|------|------| -| 设计索引 | [设计索引](docs/zh/DESIGN.md) | -| 架构设计 | [架构设计](docs/zh/design/architecture.md) | -| SDK API 设计 | [SDK API 设计](docs/zh/design/sdk-api-design.md) | -| 模板系统 | [模板系统](docs/zh/design/template-system.md) | - -### 其他资源 - -| 资源 | 链接 | -|------|------| -| 更新日志 | [CHANGELOG.md](CHANGELOG.md) | -| 贡献指南 | [CONTRIBUTING.md](.github/CONTRIBUTING.md) | -| 许可证 | [Apache-2.0](LICENSE) | -| 示例代码 | [examples/](examples/) | -| SDK skill | [agent-sandbox-sdk/SKILL.md](agent-sandbox-sdk/SKILL.md) — agent 如何写客户端和模板 | - -## 相关：abx CLI - -命令行工具 `abx`（`@agent-sandbox/cli`，Node.js）在 [`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库中开发， -与本 SDK 共享沙箱、模板与凭证。其安装方式、命令参考、教程、MCP Server 命令以及 Agent Skill（`SKILL.md`） -均在该仓库中维护： - -- [CLI README](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/README.zh-CN.md) —— 安装（[CLI binary installation](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/binary-installation.md)） -- [CLI 教程](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/guide/cli-tutorial.md) · [CLI 参考](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/reference/cli-reference.md) -- [Agent Skill 安装与分发](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/guide/agent-skill-installation.md) - -## 贡献 - -欢迎贡献！请阅读 [贡献指南](.github/CONTRIBUTING.md) 了解详情。 +| 任务 | 指南 | +| --- | --- | +| 完成第一次 API 调用 | [快速开始](docs/zh/guide/getting-started.md) | +| 查询方法与数据模型 | [API 参考](docs/zh/reference/api-reference.md) | +| 配置凭据与端点 | [认证](docs/zh/guide/authentication.md) | +| 配置文件与进程行为 | [文件与命令控制](docs/zh/guide/file-and-command-controls.md) | +| 迁移已有 E2B 代码 | [迁移指南](docs/zh/guide/migrate-from-e2b.md) | +| 处理错误 | [故障排查](docs/zh/guide/troubleshooting.md) | -## 许可证 +更多内容见[完整文档索引](docs/README.md)、[示例](examples/README.zh-CN.md)和[更新日志](CHANGELOG.md)。 -[Apache-2.0](LICENSE) —— 版权信息见 [`NOTICE`](NOTICE)。 +## 相关工具：abx CLI -[内置运行通道与 Python 引擎迁移](docs/zh/design/builtin-data-plane.md). +[abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox)提供终端操作、模板构建与启动功能，需要时单独安装。 -暂停/恢复和快照命令由 Provider 注册，CLI 与 SDK 共用实现，见[注册与使用说明](docs/zh/guide/provider-commands.md)。 +## 参与贡献 -命名命令支持原生 `list[str]` JSON 参数，校验和服务器兼容性见[服务器 API 指南](docs/zh/guide/template-server-api.md#字符串数组命令参数)。 +开发环境和两个包的检查要求见[贡献指南](.github/CONTRIBUTING.md)。SDK 与运行时问题请提交到[本仓库 Issues](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues)。 -Current API / 当前接口: [development contract](docs/zh/guide/current-api.md). +## 许可证 -[极速版认证与所需权限](docs/zh/guide/permissions.md)：已有 API Key，或经显式确认的 AK/SK 管理 Key。 +[Apache-2.0](LICENSE)，署名信息见 [NOTICE](NOTICE)。