From e2a1a2663a9acf5875d6e551f933d6a18c1a5946 Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Sat, 24 Oct 2026 19:54:26 +0000 Subject: [PATCH 1/3] docs: synchronize current usage and engineering records --- .agents/README.md | 17 +++++- .../2026-10-24-current-docs-and-records.md | 24 ++++++++ .../2026-10-23-template-workflow-contract.md | 6 +- .../2026-10-24-current-docs-and-records.md | 26 ++++++++ .../2026-10-24-python-alpha-release.md | 6 +- .github/CONTRIBUTING.md | 18 +----- CHANGELOG.md | 5 ++ README.md | 61 ++++++------------- README.zh-CN.md | 59 ++++++------------ docs/en/guide/client-sdk.md | 9 ++- docs/en/guide/sdk-usage.md | 40 +++--------- docs/en/guide/session-persistence.md | 8 ++- docs/zh/guide/client-sdk.md | 9 ++- docs/zh/guide/sdk-usage.md | 40 +++--------- docs/zh/guide/session-persistence.md | 8 ++- 15 files changed, 157 insertions(+), 179 deletions(-) create mode 100644 .agents/evidence/verify/2026-10-24-current-docs-and-records.md rename .agents/notes/{proposed => implemented}/architecture/2026-10-23-template-workflow-contract.md (91%) create mode 100644 .agents/notes/implemented/process/2026-10-24-current-docs-and-records.md rename .agents/notes/{proposed => implemented}/process/2026-10-24-python-alpha-release.md (87%) diff --git a/.agents/README.md b/.agents/README.md index b01fb870..0743015b 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -1,5 +1,18 @@ # `.agents/` — engineering record of the python-sdk repository +## Current delivery — 2026-10-24 + +- Published client/server pair: **0.3.1a5**, with [immutable public artifacts, fresh installation and retained propagation failure](evidence/verify/2026-10-24-python-a5-public-release.md). This is an alpha release; host installation does not update in-image runtimes. +- Standard `Sandbox`/`AsyncSandbox` and `code_interpreter` clients retain their migration contract. Asynchronous `ProviderSandbox` owns provider/server extensions; [SDK usage](../docs/en/guide/sdk-usage.md) now keeps process execution, interpreter calls, application HTTP and resource cleanup separate. +- Python consumes installed Node providers through the CLI engine; exec/rest providers run directly. [Provider guidance](../docs/en/guide/providers.md) owns the language boundary and content-based Git catalog updates. +- [Managed workflow acceptance](evidence/verify/2026-10-24-managed-native-workflows.md) and [proxy application authentication](evidence/verify/2026-10-24-application-proxy-token.md) record their exact operations. Unified interpreter support is not implied by shell execution on an interpreter image. +- The [92-case matrix](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/78c30fbbd186cb59c3a0f0abd9fdf85b10c84b35/.agents/evidence/verify/2026-10-24-public-template-matrix.md) used public client/server host installation 0.3.1a5 and CLI 0.4.16. Dockerfile runtime pins remained their own inputs; real-model, PTY and desktop claims remain outside that matrix. + +[Documentation synchronization decision](notes/implemented/process/2026-10-24-current-docs-and-records.md) · [verification and acceptance reconciliation](evidence/verify/2026-10-24-current-docs-and-records.md). + +Earlier entries below are a decision history. A remaining proposal is not a current product guarantee; read the linked acceptance scope before treating its full criteria as complete. + + - [Native process OS user](notes/implemented/feature/2026-10-24-native-process-user.md) · [verification](evidence/verify/2026-10-24-native-process-user.md) Maintainer and AI-agent facing records of **why** the code looks the way it does. Nothing here is imported or @@ -110,7 +123,7 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ - [Current compatibility-removal documentation verification](evidence/verify/2026-10-22-remove-legacy-docs.md). -- [Explicit template workflows](notes/proposed/architecture/2026-10-23-template-workflow-contract.md) · [canonical vectors](evidence/verify/2026-10-23-workflow-foundation.md) · [provider operations](evidence/verify/2026-10-23-provider-workflow-operations.md) · [independent second-round review](evidence/verify/2026-10-23-workflow-round2-independent.md). +- [Explicit template workflows](notes/implemented/architecture/2026-10-23-template-workflow-contract.md) · [canonical vectors](evidence/verify/2026-10-23-workflow-foundation.md) · [provider operations](evidence/verify/2026-10-23-provider-workflow-operations.md) · [independent second-round review](evidence/verify/2026-10-23-workflow-round2-independent.md). - [Workflow runtime implementation and review](evidence/verify/2026-10-23-workflow-runtime-review.md). - [Workflow migration real-cloud acceptance](evidence/verify/2026-10-23-workflow-real-cloud.md). - [Workflow CI follow-up](evidence/verify/2026-10-23-workflow-ci-followup.md). @@ -124,7 +137,7 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ - [Complete OpenSandbox workflow acceptance](evidence/verify/2026-10-23-workflow-opensandbox-acceptance.md). - [Provider error reference anchors](evidence/verify/2026-10-23-workflow-provider-error-anchors.md). -- [Python alpha release](notes/proposed/process/2026-10-24-python-alpha-release.md) · [verification](evidence/verify/2026-10-24-python-alpha-release.md) +- [Python alpha release](notes/implemented/process/2026-10-24-python-alpha-release.md) · [verification](evidence/verify/2026-10-24-python-alpha-release.md) - [Python alpha real-component acceptance](evidence/verify/2026-10-24-python-alpha-cloud.md). diff --git a/.agents/evidence/verify/2026-10-24-current-docs-and-records.md b/.agents/evidence/verify/2026-10-24-current-docs-and-records.md new file mode 100644 index 00000000..cbfd1594 --- /dev/null +++ b/.agents/evidence/verify/2026-10-24-current-docs-and-records.md @@ -0,0 +1,24 @@ +# Verification: current documentation and engineering records + +- Date: 2026-10-24 +- Result: PASS for local documentation checks; latest-head remote CI and review remain merge gates. +- Baseline: `04e8a716aa341ca2c15c48bc0bc94c3adf8d5848`. +- Scope: current Markdown documentation, lifecycle moves and owner index; no runtime or package change. + +## Accepted note reconciliation + +The GitHub API returned an actual merged timestamp and merge SHA for each linked PR: +- `2026-10-24-python-alpha-release`: [merged PR #91](https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/91). +- `2026-10-23-template-workflow-contract`: [merged PR #89](https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/89). + +This updates the notes' lifecycle, not the historical observations in their evidence. Subsequent source preparation, release and runtime acceptance is linked from the current `.agents/README.md` entry. Older proposals outside this scope retain their original state where their full acceptance criteria have not been re-established. + +## Validation + +- PASS: `bash scripts/check-repo-health.sh`: 106 passes, one existing recommendation warning, zero failures; `make hygiene`; `git diff --check`. +- PASS: all 292 relative links in changed/new Markdown resolved locally; 12 Python blocks in the modified README/client/session pages parsed with `ast.parse`. +- PASS: a fresh environment installed public `agent-sandbox-client==0.3.1a5` and its matching server. Public imports and current ProviderSandbox method names were checked. The actual `LocalSessionStore` saved, loaded, listed and deleted a temporary record; temporary storage was removed. +- Independent review caught an incorrect draft inference that Python named sessions had been removed along with the CLI command. That draft was discarded: the final guide preserves the SDK feature, corrects the real `SessionManager` import and `list_sessions()` method, and distinguishes local metadata from remote snapshots and confirmed cleanup. +- The full process/file/server guide is retained. Only the obsolete installation claim, default-code-capability promise and unsupported Express interpreter example were replaced; the README uses explicit process execution and cleanup. + +No new cloud resources or task credentials were created. Existing real-component receipts are references, not reruns under this documentation revision. The normal remote CI matrix remains mandatory; no runtime or publication workflow is weakened for this documentation change. diff --git a/.agents/notes/proposed/architecture/2026-10-23-template-workflow-contract.md b/.agents/notes/implemented/architecture/2026-10-23-template-workflow-contract.md similarity index 91% rename from .agents/notes/proposed/architecture/2026-10-23-template-workflow-contract.md rename to .agents/notes/implemented/architecture/2026-10-23-template-workflow-contract.md index 2e170f7e..fcbc3d25 100644 --- a/.agents/notes/proposed/architecture/2026-10-23-template-workflow-contract.md +++ b/.agents/notes/implemented/architecture/2026-10-23-template-workflow-contract.md @@ -1,6 +1,6 @@ # Decision: Explicit template workflows and operation contracts -Status: proposed +Status: implemented ## Problem Template application services, provider interpreter APIs and consuming clients were conflated. A code feature could incorrectly block an otherwise executable application, while shell fallback could conceal a missing interpreter. @@ -36,3 +36,7 @@ Python and CLI pass the same vectors. Package copies match canonical bytes. Curr - [Native startup acknowledgment correction](../../../evidence/verify/2026-10-23-native-startup-acknowledgment.md). - [Complete OpenSandbox application workflow](../../../evidence/verify/2026-10-23-workflow-opensandbox-acceptance.md). + +## Implementation + +Delivered in [PR #89](https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/89); actual merged state was checked on 2026-10-24. Later acceptance and current limitations are indexed in the [current synchronization record](../../../evidence/verify/2026-10-24-current-docs-and-records.md). Earlier verification files remain unchanged and retain their original pending or failed observations. diff --git a/.agents/notes/implemented/process/2026-10-24-current-docs-and-records.md b/.agents/notes/implemented/process/2026-10-24-current-docs-and-records.md new file mode 100644 index 00000000..58ea7ad3 --- /dev/null +++ b/.agents/notes/implemented/process/2026-10-24-current-docs-and-records.md @@ -0,0 +1,26 @@ +# Decision: Synchronize current documentation and accepted records +Status: implemented + +## Problem +Current user guides and engineering entry points still contain stale installation, usage or pending-status descriptions after recent delivery. + +## Decision +Update only this owner's current guides and index the actual release, implementation and verification boundaries. Reconcile dated notes with verified merged PRs. Preserve merged evidence verbatim and keep source/provider/consumer versions explicit. + +## API Design +N/A — documentation only; no runtime API, package version or publication changes. + +## Alternatives considered +Do not copy a whole cross-repository report or rewrite historical failures into passes. Do not infer broad platform support from an unrelated passing test. + +## Dependencies +The already-merged owner PRs and dated receipts linked in this repository's engineering index. Related repositories own their own documentation and records. + +## Test Strategy +Run document/record/link checks and the normal remote CI gates. Check examples against the current public API and existing real-component evidence. No cloud rerun is needed for this documentation-only synchronization. + +## Acceptance criteria +Current English/Chinese instructions agree with implemented entry points; accepted notes match their state directory; local links resolve; old evidence is unchanged; required latest-head CI and independent review pass before merge. + +## Evidence +[Verification](../../../evidence/verify/2026-10-24-current-docs-and-records.md). diff --git a/.agents/notes/proposed/process/2026-10-24-python-alpha-release.md b/.agents/notes/implemented/process/2026-10-24-python-alpha-release.md similarity index 87% rename from .agents/notes/proposed/process/2026-10-24-python-alpha-release.md rename to .agents/notes/implemented/process/2026-10-24-python-alpha-release.md index 0d9b3e8c..6e850949 100644 --- a/.agents/notes/proposed/process/2026-10-24-python-alpha-release.md +++ b/.agents/notes/implemented/process/2026-10-24-python-alpha-release.md @@ -1,6 +1,6 @@ # Decision: Publish an explicitly verified Python alpha pair -Status: proposed +Status: implemented ## Problem @@ -41,3 +41,7 @@ Run full client/server tests, lint/type/format, lockstep checks, actual Python-t ## Evidence See [verification](../../../evidence/verify/2026-10-24-python-alpha-release.md). Remote CI, PR review and publication status are recorded on the linked owner Issue and PR; local build alone is not a published release. + +## Implementation + +Delivered in [PR #91](https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/91); actual merged state was checked on 2026-10-24. Later acceptance and current limitations are indexed in the [current synchronization record](../../../evidence/verify/2026-10-24-current-docs-and-records.md). Earlier verification files remain unchanged and retain their original pending or failed observations. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 513c408f..e91f119c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -174,23 +174,7 @@ logged or committed. The full rule, the evidence-file and ADR templates are in Sandbox templates — content, the machine-readable index (`awesome-templates.yaml`), releases and CI — live in the dedicated repository **[alibaba-agent-sandbox/awesome-templates](https://github.com/alibaba-agent-sandbox/awesome-templates)**. It is the single source of truth for official & community templates; this repository no longer bundles a template collection (it keeps only a minimal `python-hello` offline fixture for tests). -### Contributing a Template - -1. **Read** the catalog repository's [CONTRIBUTING.md](https://github.com/alibaba-agent-sandbox/awesome-templates/blob/main/CONTRIBUTING.md) — it defines the template anatomy, capability-group rules, and local dev workflow. -2. **Open a PR** against [alibaba-agent-sandbox/awesome-templates](https://github.com/alibaba-agent-sandbox/awesome-templates) that adds your template folder and updates `awesome-templates.yaml` (plus the README template table) in the same PR. -3. **Required index fields**: `name`, `description`, `repo`, `tags`, `author`, `status` (optional: `path` for subdirectory templates, `ref` to pin a version). -4. **Status values**: - - `official` — maintained by the alibaba-agent-sandbox team (do not use for community PRs) - - `community` — community-contributed and maintained - - `experimental` — early-stage or proof-of-concept -5. **Ensure** your repo contains a valid `template.yaml` at the specified path. The catalog CI validates every folder and the index offline. - -### Template Repository Requirements - -Your template repository should include: -- A `template.yaml` declaring specification 4, `provides`, explicit `workflows` and `default_workflow` -- A `Dockerfile` and a `README.md` with usage instructions -- Example code or scripts that demonstrate the template's purpose +Read the owning repository's [contributor guide](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/CONTRIBUTING.md) and [template specification](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/template-spec.md) before submitting there. Those files own the current manifest, catalog fields and required validation. Maintenance labels do not certify runtime behavior. Do not duplicate their schema or a template-status checklist in this SDK repository. ### Searching Templates diff --git a/CHANGELOG.md b/CHANGELOG.md index e9fb89f3..75076a4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ## [Unreleased] +### Documentation synchronization + +- Correct current SDK examples, reconnect semantics and installation guidance; index accepted release/workflow records without rewriting historical verification. / 修正当前 SDK 示例、重连语义与安装说明，索引已交付发布和工作流记录，保留历史验证。 + + ### Documentation - Simplify the bilingual Provider guide to actual entry points, correct installation verification guarantees and link complete authoring manifests. / 将中英文 Provider 指南收敛到实际调用入口，修正安装验证承诺，并引用完整的编写示例。 diff --git a/README.md b/README.md index 82a7b596..debbceef 100644 --- a/README.md +++ b/README.md @@ -48,10 +48,9 @@ Provider management operations are available through `agent_sandbox.providers.co ## Client SDK - **Sync and async standard clients** — `Sandbox.create()` and `AsyncSandbox.create()`, shell execution, code interpretation, file I/O, port forwarding, and WebSocket streaming. -- **Three execution primitives** — `sandbox.commands.run()` (bare shell), `sandbox.run_code()` (code interpreter), `sandbox.run("name", **kwargs)` (a command the Server SDK registered). +- **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. -- **Session persistence** — save and restore sandbox state across runs. - **Standard sync/async clients** — `agent_sandbox` exports the standard Sandbox and AsyncSandbox; see [Migrate from E2B](docs/en/guide/migrate-from-e2b.md). ## Server SDK @@ -91,57 +90,37 @@ finally: ## Provider and server extensions - -Set `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL` and `ABX_SANDBOX_DOMAIN` before creating a sandbox. This snippet uses `python-base` because that image registers `hello`. `Sandbox.create()` with no template uses `base`. +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 as Sandbox +from agent_sandbox import ProviderSandbox async def main(): - async with await Sandbox.create(template="python-base") as sandbox: - - # 1. Bare shell — sandbox.commands.run(cmd) - proc = await sandbox.commands.run("echo 'Hello from sandbox!'") - print(proc.stdout) # Hello from sandbox! - print(proc.exit_code) # 0 - - # 2. Code interpreter — sandbox.run_code(code) - result = await sandbox.run_code("print(2 ** 10)") - print(result.text) # 1024 - - # 3. Named command — sandbox.run(name, **kwargs) - # POST /commands/hello on the in-sandbox SandboxServer - greeting = await sandbox.run("hello", name="Alice") - print(greeting) # the registered function's return value - - # 4. File operations - await sandbox.files.write("/tmp/data.txt", "content") - content = await sandbox.files.read("/tmp/data.txt") - - # 5. Port access - url = sandbox.network.get_url(3000) + 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()) ``` -## Execution API - -Three execution methods, each for a distinct use case: +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. -| Method | Purpose | Returns | -|--------|---------|---------| -| `sandbox.commands.run(cmd)` | Execute a bare shell command (raw exec) | `ProcessResult` — `.stdout`, `.stderr`, `.exit_code` | -| `sandbox.run_code(code)` | Execute code via the code interpreter | `CodeResult` — `.text`, `.stdout`, `.stderr` | -| `sandbox.run(name, **kw)` | Call a command registered in the sandbox server | the registered function's JSON return value | +## Execution API -**Named commands** have one mechanism: server-side registered commands. A command is registered with -`@sandbox.register` (or `CommandRegistry`) inside the template, and `sandbox.run("name", **kwargs)` sends -`POST /commands/name` to the in-sandbox SandboxServer. An unknown name raises `CommandNotFoundError`; -`await sandbox.list_commands()` lists what the server has registered. See -[Declarative Usage](docs/en/guide/declarative-usage.md). +| 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 | -> **Environment variables:** envd uses direct exec — shell features (`$VAR`, pipes, redirects) require `sh -c '...'`. Use `printenv VAR` to read a variable. See the [Environment Variables guide (EN)](docs/en/guide/environment-variables.md) | [环境变量指南 (中文)](docs/zh/guide/environment-variables.md) for details. +Named application commands are registered by the in-sandbox server. Follow [template workflows](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. ## Templates diff --git a/README.zh-CN.md b/README.zh-CN.md index c6824056..df1e7b11 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -46,10 +46,9 @@ Node.js 项目，位于 [`agent-sandbox`](https://github.com/alibaba-agent-sandb ## Client SDK - **同步与异步标准客户端** —— `Sandbox.create()` 与 `AsyncSandbox.create()`，Shell 执行、代码解释、文件读写、端口转发与 WebSocket 流；Provider／Server 扩展使用异步 `ProviderSandbox`。 -- **三种执行原语** —— `sandbox.commands.run()`（裸 Shell）、`sandbox.run_code()`（代码解释器）、`sandbox.run("name", **kwargs)`（调用 Server SDK 注册的命令）。 +- **明确的执行入口** —— 进程执行、标准解释器客户端、模板应用命令各有对应的运行时要求（见下方执行 API）。 - **MCP Server** —— 将沙箱操作暴露为 MCP 工具，供 LLM Agent 调用。 - **声明式装饰器** —— `@sandbox` 将普通函数变为远程沙箱执行，自动序列化。 -- **会话持久化** —— 跨运行保存和恢复沙箱状态。 - **标准同步与异步客户端** —— `agent_sandbox` 导出标准 Sandbox 与 AsyncSandbox，见[从 E2B 迁移](docs/zh/guide/migrate-from-e2b.md)。 ## Server SDK @@ -89,55 +88,37 @@ finally: ## Provider 与 Server 扩展 - -第一次创建之前先设置 `ABX_SANDBOX_API_KEY`。SDK 读取这三个标准连接变量。下面的例子用 `python-base`，因为这张镜像注册了 `hello`。不传 template 的 `Sandbox.create()` 使用 `base`。 +设置 `ABX_SANDBOX_API_KEY`、`ABX_SANDBOX_BASE_URL` 和 `ABX_SANDBOX_DOMAIN` 后，使用 `ProviderSandbox` 创建原生实例并执行进程： ```python import asyncio -from agent_sandbox import ProviderSandbox as Sandbox +from agent_sandbox import ProviderSandbox async def main(): - async with await Sandbox.create(template="python-base") as sandbox: - - # 1. 裸 Shell —— sandbox.commands.run(cmd) - proc = await sandbox.commands.run("echo 'Hello from sandbox!'") - print(proc.stdout) # Hello from sandbox! - print(proc.exit_code) # 0 - - # 2. 代码解释器 —— sandbox.run_code(code) - result = await sandbox.run_code("print(2 ** 10)") - print(result.text) # 1024 - - # 3. 命名命令 —— sandbox.run(name, **kwargs) - # 向沙箱内 SandboxServer 发送 POST /commands/hello - greeting = await sandbox.run("hello", name="Alice") - print(greeting) # 注册函数的返回值 - - # 4. 文件操作 - await sandbox.files.write("/tmp/data.txt", "content") - content = await sandbox.files.read("/tmp/data.txt") - - # 5. 端口访问 - url = sandbox.network.get_url(3000) + 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()) ``` -## 执行 API - -三种执行方法，分别对应不同场景： +这里的 `python3` 是一次进程执行，不是持久代码解释器。Provider 未实现的解释器操作会返回 `E8004`；上方标准 `code_interpreter.Sandbox` 是独立入口。`close()` 只关闭客户端连接，删除实例使用 `kill()`。 -| 方法 | 用途 | 返回类型 | -|------|------|----------| -| `sandbox.commands.run(cmd)` | 执行裸 Shell 命令（原始 exec） | `ProcessResult` —— `.stdout`, `.stderr`, `.exit_code` | -| `sandbox.run_code(code)` | 通过代码解释器执行代码 | `CodeResult` —— `.text`, `.stdout`, `.stderr` | -| `sandbox.run(name, **kw)` | 调用注册在沙箱 server 里的命令 | 注册函数的 JSON 返回值 | +## 执行 API -**命名命令**只有一种机制：服务端注册命令。在模板里用 `@sandbox.register`（或 `CommandRegistry`）注册， -`sandbox.run("name", **kwargs)` 向沙箱内 SandboxServer 发送 `POST /commands/name`。名字不存在抛 -`CommandNotFoundError`；`await sandbox.list_commands()` 列出 server 已注册的命令。见[声明式用法](docs/zh/guide/declarative-usage.md)。 +| 入口 | 用途 | 前提 | +|---|---|---| +| `ProviderSandbox.commands.run()` | 执行进程，读取 stdout、stderr 和退出码 | Provider 实现进程操作 | +| 标准 `code_interpreter.Sandbox.run_code()` | 执行解释器代码 | 使用 `code-interpreter-v1` 等对应原生运行时 | +| `ProviderSandbox.application_client()` | 调用模板 HTTP 服务注册的应用命令 | 先启动模板服务，传入正确端口与应用令牌 | -> **环境变量：** envd 使用直接执行（direct exec）—— Shell 特性（`$VAR` 展开、管道、重定向）需要 `sh -c '...'`。用 `printenv VAR` 读取变量值。详见[环境变量指南（中文）](docs/zh/guide/environment-variables.md) | [Environment Variables (EN)](docs/en/guide/environment-variables.md)。 +命名应用命令由沙箱内服务端注册。通过 [模板工作流](docs/zh/guide/template-workflows.md) 创建或连接对应应用，保留 Provider 返回的网关请求头、URL 前缀和查询参数；不要假定 `base` 注册了 `hello`。Provider 插件的跨语言执行方式见 [Provider 指南](docs/zh/guide/providers.md)。 ## 模板 diff --git a/docs/en/guide/client-sdk.md b/docs/en/guide/client-sdk.md index 7aa7a488..68da0103 100644 --- a/docs/en/guide/client-sdk.md +++ b/docs/en/guide/client-sdk.md @@ -1,13 +1,12 @@ # Client SDK -For current SDK installation, use the [paired source installation guide](install-python.md). +For current SDK installation, use the [installation guide](install-python.md). The Client SDK runs on **your machine**. It creates a sandbox, connects to one that already exists, and then runs commands, reads and writes files, and calls the code interpreter. The package is `agent-sandbox-client`. Import `agent_sandbox`. ```bash -python -m pip install \ - "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/3aa5e5ae6bd9c843f62c6689e549437f460b382d.tar.gz#subdirectory=server-sdk" \ - "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/3aa5e5ae6bd9c843f62c6689e549437f460b382d.tar.gz#subdirectory=client-sdk" +python -m pip install 'agent-sandbox-client==0.3.1a5' +python -m pip check ``` Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated project. @@ -15,7 +14,7 @@ Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated projec ```python from agent_sandbox import ProviderSandbox as Sandbox -async with await Sandbox.create(template="python-base") as sandbox: +async with await Sandbox.create(template="base") as sandbox: result = await sandbox.commands.run("echo hello") print(result.stdout) ``` diff --git a/docs/en/guide/sdk-usage.md b/docs/en/guide/sdk-usage.md index 0aadcc42..1d9ce997 100644 --- a/docs/en/guide/sdk-usage.md +++ b/docs/en/guide/sdk-usage.md @@ -6,7 +6,7 @@ This page documents the asynchronous **ProviderSandbox** provider/server extensi ## Installation -Follow the [paired source installation guide](install-python.md). The client/server0.3.0 packages are not yet published on PyPI; install both from the same tested revision. +Follow the [installation guide](install-python.md). The public client/server alpha pair is 0.3.1a5; installing the client installs the matching server dependency. Host package installation does not change existing sandbox images. Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated project. @@ -18,6 +18,10 @@ from agent_sandbox import ProviderSandbox as Sandbox --- +## Current application binding + +The template-author example below retains its explicit deployment prerequisite. When connecting to an existing instance returned by the CLI, obtain an application client with `await sandbox.application_client(9000, token=application_token, timeout=330)` and call `client.commands.run(...)`; see [template workflows](template-workflows.md). This preserves provider gateway headers, URL prefixes and signed query parameters. `close()` releases a connection; `kill()` deletes an instance. Do not delete a borrowed instance. An HTTP wait timeout does not guarantee remote cancellation and does not automatically replay a command. + ## Template author quick path Verified 2026-10-15 on Alibaba Cloud Express (`alicloud-express`) with a generation-2 template whose start command runs `agent-sandbox-server`. `Sandbox.create(template=..., provider="alicloud-express")` uses `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL`, and `ABX_SANDBOX_DOMAIN`. The template argument is the template id or its name. @@ -84,8 +88,8 @@ Automatically calls `kill()` to destroy the sandbox when exiting the `with` bloc ```python async with await Sandbox.create(template="base") as sandbox: - result = await sandbox.run_code("print(1+1)") - print(result.text) # "2" + result = await sandbox.commands.run("python3 -c 'print(1+1)'") + print(result.stdout) # "2" # Automatically destroyed ``` @@ -123,35 +127,9 @@ for sb in sandboxes: ## Execute Code — run_code -Execute code via the Code Interpreter: - -```python -result = await sandbox.run_code( - "print('hello')", - language="python", # Default "python" - timeout=30, # Timeout in seconds (default 30) - envs={"KEY": "val"}, # Temporary env vars for this execution (envd scope) -) - -print(result.text) # Output text (stdout with trailing whitespace stripped) -print(result.stdout) # Raw stdout -print(result.stderr) # Raw stderr -print(result.exit_code) # Exit code -print(result.execution_time) # Execution time (seconds) -print(result.output_files) # Output file list [OutputFile] -``` - -Callback support: - -```python -result = await sandbox.run_code( - "for i in range(3): print(i)", - on_stdout=lambda s: print(f"[OUT] {s}"), - on_stderr=lambda s: print(f"[ERR] {s}"), -) -``` +Provider interpretation requires exact operations such as `code.execute` or `code.default-context.execute`; see [template workflows](template-workflows.md#interpreter-operations). The Express project adapter does not implement unified interpretation and returns `E8004`, without falling back to script execution. Running a Python process on `base` does not establish persistent code contexts. -> **Capability requirement**: Requires the `code` capability (included in the default capability set `{shell, files, code}`). +For the native Express interpreter, use the separate standard `agent_sandbox.code_interpreter` client and `code-interpreter-v1`, following [migration](migrate-from-e2b.md) for sync/async calls and result models. Streaming callbacks also require their actual operation; a buffered result does not establish realtime streaming. --- diff --git a/docs/en/guide/session-persistence.md b/docs/en/guide/session-persistence.md index 9f9080b7..34384b22 100644 --- a/docs/en/guide/session-persistence.md +++ b/docs/en/guide/session-persistence.md @@ -1,6 +1,8 @@ # Session Persistence -For current SDK installation, use the [paired source installation guide](install-python.md). +The SDK still provides `LocalSessionStore` and `SessionManager`; the removed surface is the CLI `abx session` group. Persistence stores local names, sandbox IDs and connection metadata, not remote memory or file snapshots, and cannot restore deleted or expired instances. `SessionManager.stop()` attempts deletion but logs and suppresses deletion errors; independently check the actual instance when confirmed cleanup is required. + +For current SDK installation, use the [installation guide](install-python.md). > **Note:** The `abx` commands shown on this page are provided by the Node.js CLI in the `cli` repository ([CLI binary installation](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/binary-installation.md)). CLI-specific documentation (CLI design, tutorial, reference) lives there too; this repository documents the Python SDK (`agent-sandbox-client`) and the container-side runtime (`agent-sandbox-server`). @@ -61,7 +63,7 @@ File reads and writes are protected by file locks: ### SDK Alternative ```python -from agent_sandbox.session import SessionManager +from agent_sandbox.api.session_manager import SessionManager manager = SessionManager() @@ -72,7 +74,7 @@ await manager.start("my-project", template="base", timeout=600) sb = await manager.connect("my-project") # List sessions -sessions = await manager.list() +sessions = await manager.list_sessions() # Stop a session await manager.stop("my-project") diff --git a/docs/zh/guide/client-sdk.md b/docs/zh/guide/client-sdk.md index 05147778..47dbc2b7 100644 --- a/docs/zh/guide/client-sdk.md +++ b/docs/zh/guide/client-sdk.md @@ -1,13 +1,12 @@ # Client SDK -当前 SDK 安装使用[配套源码安装指南](install-python.md)。 +当前 SDK 安装使用[安装指南](install-python.md)。 Client SDK 跑在**你的机器**上。它创建沙箱、连上已经存在的沙箱，然后在沙箱里执行命令、读写文件、调用代码解释器。包名是 `agent-sandbox-client`，导入 `agent_sandbox`。 ```bash -python -m pip install \ - "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/3aa5e5ae6bd9c843f62c6689e549437f460b382d.tar.gz#subdirectory=server-sdk" \ - "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/3aa5e5ae6bd9c843f62c6689e549437f460b382d.tar.gz#subdirectory=client-sdk" +python -m pip install 'agent-sandbox-client==0.3.1a5' +python -m pip check ``` 不要执行 `pip install agent-sandbox`。PyPI 上的 `agent-sandbox` 是另一个无关项目。 @@ -15,7 +14,7 @@ python -m pip install \ ```python from agent_sandbox import ProviderSandbox as Sandbox -async with await Sandbox.create(template="python-base") as sandbox: +async with await Sandbox.create(template="base") as sandbox: result = await sandbox.commands.run("echo hello") print(result.stdout) ``` diff --git a/docs/zh/guide/sdk-usage.md b/docs/zh/guide/sdk-usage.md index 0c015d79..b45da6f5 100644 --- a/docs/zh/guide/sdk-usage.md +++ b/docs/zh/guide/sdk-usage.md @@ -7,7 +7,7 @@ ## 安装 -请按[配套源码安装指南](install-python.md)安装。客户端/服务端0.3.0尚未发布到 PyPI；应从同一已验证提交安装两个发行包。 +请按[安装指南](install-python.md)安装。公开客户端/服务端 alpha 版本为 0.3.1a5；安装客户端会安装匹配的服务端依赖。宿主机安装不会更新已有沙箱镜像。 不要执行 `pip install agent-sandbox`。PyPI 上的 `agent-sandbox` 是另一个无关项目。 @@ -19,6 +19,10 @@ from agent_sandbox import ProviderSandbox as Sandbox --- +## 当前应用连接 + +下面的模板作者示例保留其明确部署前提。连接 CLI 返回的已有实例时，优先通过 `await sandbox.application_client(9000, token=application_token, timeout=330)` 获取应用客户端，再调用 `client.commands.run(...)`；见[模板工作流](template-workflows.md)。它保留 Provider 网关头、URL 前缀与签名查询参数。`close()` 只释放连接，`kill()` 删除实例；不要销毁借用的实例。HTTP 等待超时不保证取消远端执行，也不会自动重试命令。 + ## 模板作者快速路径 2026-10-15 在阿里云 Express（`alicloud-express`）上验证。模板是 generation 2，启动命令运行 `agent-sandbox-server`。`Sandbox.create(template=..., provider="alicloud-express")` 使用 `ABX_SANDBOX_API_KEY`、`ABX_SANDBOX_BASE_URL` 和 `ABX_SANDBOX_DOMAIN`。`template` 可以是模板 id 或名称。 @@ -85,8 +89,8 @@ sandbox = Sandbox.create_sync(template="base") ```python async with await Sandbox.create(template="base") as sandbox: - result = await sandbox.run_code("print(1+1)") - print(result.text) # "2" + result = await sandbox.commands.run("python3 -c 'print(1+1)'") + print(result.stdout) # "2" # 自动销毁 ``` @@ -124,35 +128,9 @@ for sb in sandboxes: ## 执行代码 — run_code -通过 Code Interpreter 执行代码： - -```python -result = await sandbox.run_code( - "print('hello')", - language="python", # 默认 "python" - timeout=30, # 超时秒数（默认 30） - envs={"KEY": "val"}, # 本次执行的临时环境变量（envd 作用域） -) - -print(result.text) # 输出文本（stdout 去除尾部空白） -print(result.stdout) # 原始 stdout -print(result.stderr) # 原始 stderr -print(result.exit_code) # 退出码 -print(result.execution_time) # 执行耗时（秒） -print(result.output_files) # 输出文件列表 [OutputFile] -``` - -支持回调： - -```python -result = await sandbox.run_code( - "for i in range(3): print(i)", - on_stdout=lambda s: print(f"[OUT] {s}"), - on_stderr=lambda s: print(f"[ERR] {s}"), -) -``` +Provider 解释器要求精确操作，如 `code.execute`、`code.default-context.execute`；详见[模板工作流](template-workflows.md#解释器操作)。极速版项目适配器未实现统一解释器，调用会返回 `E8004`，不会自动回退到执行脚本。`base` 上运行 Python 进程不代表支持持久代码上下文。 -> **能力要求**：需要 `code` 能力（包含在默认能力集 `{shell, files, code}` 中）。 +若需极速版原生解释器，请使用独立标准 `agent_sandbox.code_interpreter` 客户端和 `code-interpreter-v1`，按[迁移指南](migrate-from-e2b.md)选择同步或异步入口及返回模型。流式回调同样需要对应的实际操作，不能从缓存结果推断实时流支持。 --- diff --git a/docs/zh/guide/session-persistence.md b/docs/zh/guide/session-persistence.md index 2f60976f..b27be84f 100644 --- a/docs/zh/guide/session-persistence.md +++ b/docs/zh/guide/session-persistence.md @@ -1,6 +1,8 @@ # 会话持久化 -当前 SDK 安装使用[配套源码安装指南](install-python.md)。 +本页的 SDK `LocalSessionStore` 和 `SessionManager` 仍存在；已移除的是 CLI 的 `abx session` 命令组。持久化内容是本地名称与沙箱 ID 等连接信息，不是远端内存或文件快照，不能恢复已删除或到期的实例。`SessionManager.stop()` 会尝试删除实例，但会记录并吞掉删除异常；需要确认资源清理时必须额外核对实际实例状态。 + +当前 SDK 安装使用[安装指南](install-python.md)。 > **说明：** 本页出现的 `abx` 命令由 `cli` 仓库中的 Node.js CLI 提供（[CLI binary installation](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/binary-installation.md)）。CLI 专属文档（CLI 设计、教程、参考）也在该仓库；本仓库记录 Python SDK（`agent-sandbox-client`）与容器侧运行时（`agent-sandbox-server`）。 @@ -61,7 +63,7 @@ ### SDK 替代方案 ```python -from agent_sandbox.session import SessionManager +from agent_sandbox.api.session_manager import SessionManager manager = SessionManager() @@ -72,7 +74,7 @@ await manager.start("my-project", template="base", timeout=600) sb = await manager.connect("my-project") # 列出会话 -sessions = await manager.list() +sessions = await manager.list_sessions() # 停止会话 await manager.stop("my-project") From bf3e1ae000fd67b439152beacdc7161c5b70416c Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:00:19 +0000 Subject: [PATCH 2/3] docs: align packaged skills with current runtime contracts --- .../2026-10-24-current-docs-and-records.md | 7 ++ CHANGELOG.md | 2 +- agent-sandbox-provider/SKILL.md | 29 +++--- agent-sandbox-sdk/SKILL.md | 95 ++++++++++++------- 4 files changed, 85 insertions(+), 48 deletions(-) diff --git a/.agents/evidence/verify/2026-10-24-current-docs-and-records.md b/.agents/evidence/verify/2026-10-24-current-docs-and-records.md index cbfd1594..2d10c515 100644 --- a/.agents/evidence/verify/2026-10-24-current-docs-and-records.md +++ b/.agents/evidence/verify/2026-10-24-current-docs-and-records.md @@ -22,3 +22,10 @@ This updates the notes' lifecycle, not the historical observations in their evid - The full process/file/server guide is retained. Only the obsolete installation claim, default-code-capability promise and unsupported Express interpreter example were replaced; the README uses explicit process execution and cleanup. No new cloud resources or task credentials were created. Existing real-component receipts are references, not reruns under this documentation revision. The normal remote CI matrix remains mandatory; no runtime or publication workflow is weakened for this documentation change. + +## Packaged skill follow-up + +Independent review found the two current skills still instructed pre-release source-only installation, and their sample manifest/feature table contradicted the delivered workflow contract. Both now install public alpha 0.3.1a5, preserve standard versus Provider credentials, use an explicitly borrowed application binding, retain valid feature IDs and declare exact consumer operations. The SDK skill's source template uses spec 4; no unsupported host-kit interpreter is invented. Skill references were scanned for the same obsolete installation claims. + +- PASS: the actual public-a5 `parse_manifest` accepts the complete REST example; `SandboxTemplate.model_validate` accepts the skill's source template. All skill Python blocks parse with `ast.parse`. +- Skill changes are instructions only. No image build, new cloud run, first Node package release or new Python package publication is claimed. diff --git a/CHANGELOG.md b/CHANGELOG.md index 75076a4e..95b6ddc1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ### Documentation synchronization -- Correct current SDK examples, reconnect semantics and installation guidance; index accepted release/workflow records without rewriting historical verification. / 修正当前 SDK 示例、重连语义与安装说明，索引已交付发布和工作流记录，保留历史验证。 +- Correct current SDK examples, reconnect semantics, packaged skills and installation guidance; index accepted release/workflow records without rewriting historical verification. / 修正当前 SDK 示例、重连语义、配套技能与安装说明，索引已交付发布和工作流记录，保留历史验证。 ### Documentation diff --git a/agent-sandbox-provider/SKILL.md b/agent-sandbox-provider/SKILL.md index 098c5da7..7532b1f7 100644 --- a/agent-sandbox-provider/SKILL.md +++ b/agent-sandbox-provider/SKILL.md @@ -9,16 +9,14 @@ This file is instructions for a coding agent. It is not executed by the SDK. Calling `Sandbox.create` against a backend that already exists is `agent-sandbox-sdk`. This skill only covers the provider you add. The client distribution is `agent-sandbox-client` (import `agent_sandbox`). -Until the first verified PyPI release, install both packages from the same public commit: +Install the verified public alpha pair; the client installs its matching server dependency: ```bash -python -m pip install \ - "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" \ - "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk" +python -m pip install 'agent-sandbox-client==0.3.1a5' +python -m pip check ``` -The image needs only `agent-sandbox-server`. After a verified PyPI release, -`pip install agent-sandbox-client==` also installs the matching server dependency. +The image needs only `agent-sandbox-server==0.3.1a5`. Installing that package on the host does not update an existing image. Development source installations must use a matching client/server revision. Do not install `agent-sandbox`; that PyPI project is unrelated. Only `alicloud-express` is built in. Do not reinstall it and do not reuse @@ -41,8 +39,8 @@ started on demand; `abx` must be on `PATH` or in `ABX_BIN`) using `EngineProvider`. Python `exec` and `rest` manifests still run in the Python process. The catalog guide is `awesome-providers/docs/zh/principle.md`. The official site is -https://www.agent-sandbox.com. The registry website is -https://registry.agent-sandbox.com. The installer index is +https://www.agent-sandbox.cn. The registry website is +https://registry.agent-sandbox.cn. The installer index is `https://registry.agent-sandbox.cn/providers/index.json`. ## Pick a kind @@ -92,7 +90,6 @@ pty get_terminal files.rw read, write, list, move, remove files.watch files.watch files.transfer upload_url / download_url -code.interpret run_code templates.read template list templates.build legacy template build templates.deploy opt-in image deployment via a provider template factory (CLI owned) @@ -103,6 +100,8 @@ network.vpc VPC sessions named commands on the in-sandbox server ``` +Interpreter and workflow calls use the separate exact `[operations]` contract, with `operation_contract_version = 1` and explicit `cli`/`python` arrays. `code.interpret` is not an accepted feature id. Declare `code.execute`, `code.default-context.execute` or context/stream operations only for implemented consumer paths. Python exec/rest bridges do not implement interpreter operations. `[workflow]` declares supported input/startup kinds; declarations do not implement the transport. See the [shared contract](https://github.com/Alibaba-Agent-Sandbox/python-sdk/tree/main/contracts). + Declare a feature only when the backend actually implements that call. A declared feature that 404s is worse than `E8004`, because the caller thinks the call was attempted for real. @@ -121,6 +120,15 @@ URL, and feature list. Drop `[core] inherit` unless the user asked for it. ```toml manifest_version = 1 +operation_contract_version = 1 + +[operations] +cli = ["sandbox.create", "sandbox.get", "sandbox.list", "sandbox.delete", "exec.run", "files.read", "files.write", "files.list", "files.stat", "files.remove", "files.move", "ports.resolve"] +python = ["sandbox.create", "sandbox.get", "sandbox.list", "sandbox.delete", "exec.run", "files.read", "files.write", "files.list", "files.stat", "files.remove", "files.move", "ports.resolve"] + +[workflow] +inputs = ["managed"] +startups = ["exec", "none"] [provider] id = "my-cloud" @@ -219,7 +227,6 @@ export default function create(kit) { sandbox_protocol: new kit.SandboxProtocol(http), process_protocol: new kit.ProcessProtocol(http), filesystem_protocol: new kit.FilesystemProtocol(http), - code_interpreter_protocol: new kit.CodeInterpreterProtocol(http), }; }, }; @@ -229,7 +236,7 @@ export default function create(kit) { The manifest sets `[compat] protocol = "node/1"` and `[runtime] kind = "node"`, `entry = "provider.mjs"`. The host gates every protocol by the declared features, so undeclared methods raise `E8004` before I/O. See -`awesome-providers/e2b/provider.mjs` and `cubesandbox/provider.mjs`. +`awesome-providers/e2b/provider.mjs` and `cubesandbox/provider.mjs`. The host kit does not supply an interpreter implementation; provide one explicitly only when declaring its exact operations. ## Before you say it works diff --git a/agent-sandbox-sdk/SKILL.md b/agent-sandbox-sdk/SKILL.md index 00121e4c..515605af 100644 --- a/agent-sandbox-sdk/SKILL.md +++ b/agent-sandbox-sdk/SKILL.md @@ -16,22 +16,19 @@ Two packages share one version: | `agent-sandbox-client` | `agent_sandbox` | The caller's machine | | `agent-sandbox-server` | `agent_sandbox.server` | Inside the image, port 9000 | -Until the first verified PyPI release, install both packages from the same public commit: +Install the verified public alpha pair; the client installs its matching server dependency: ```bash -python -m pip install \ - "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" \ - "agent-sandbox-client @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk" +python -m pip install 'agent-sandbox-client==0.3.1a5' +python -m pip check ``` -The image needs only `agent-sandbox-server`. After a verified PyPI release, -`pip install agent-sandbox-client==` also installs the matching server dependency. +The image needs only `agent-sandbox-server==0.3.1a5`. Installing that package on the host does not update an existing image. Development source installations must use a matching client/server revision. Do not run `pip install agent-sandbox`. That PyPI name is an unrelated project. ## Credentials -The client reads `E2B_API_KEY` from the process environment, `./.env`, -or `~/.abx/.env`. The canonical connection settings are E2B_API_KEY, E2B_API_URL and E2B_DOMAIN; project/home configuration supplies their fallback. Explicit standard SDK keywords take precedence. +ProviderSandbox reads `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL` and `ABX_SANDBOX_DOMAIN`. Standard clients also map the E2B environment names according to the [migration contract](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/migrate-from-e2b.md). Preserve the selected entry's configuration; never forward a control-plane key as an application token. AK/SK, when a call needs them, are `ALICLOUD_ACCESS_KEY_ID` and `ALICLOUD_ACCESS_KEY_SECRET`. Never print a key, never commit one, and never @@ -70,25 +67,36 @@ for custom providers, named server commands, sessions and declarative execution. Do not import the root standard Sandbox for these examples. +First launch the application template through the CLI. Set `SANDBOX_ID` to its returned instance ID, `ABX_PROVIDER` to its owning provider and `ABX_SERVER_TOKEN` to the application token configured before launch. `base` does not imply a registered `hello` command. + ```python import asyncio -from agent_sandbox import ProviderSandbox as Sandbox +import os +from agent_sandbox import ProviderSandbox async def main() -> None: - async with await Sandbox.create(template="python-hello", timeout=300) as sb: - result = await sb.commands.run("python3 --version", timeout=30) - print(result.stdout) - print(await sb.run("hello", name="Ada")) + sb = await ProviderSandbox.connect( + os.environ["SANDBOX_ID"], provider=os.environ["ABX_PROVIDER"] + ) + try: + async with await sb.application_client( + 9000, token=os.environ["ABX_SERVER_TOKEN"], timeout=330 + ) as client: + print(await client.commands.run("hello", name="Ada")) + finally: + await sb.close() # borrowed instance; its owner deletes it asyncio.run(main()) ``` +This binding preserves the provider gateway's headers and full URL/query. Explicit application tokens also use `X-Access-Token` only when that header is free; gateway credentials are never overwritten. Request timeout does not cancel remote work or replay the command. + - `timeout` on `create` is how long the sandbox lives, not the HTTP timeout. `request_timeout` bounds the create HTTP call. - A shell command is `sb.commands.run`. A function registered in `commands.py` is `sb.run(name, **kwargs)`, which returns the unwrapped `result`. - `sb.commands.run` wraps an unquoted pipe, redirect, or `&&` in `sh -c`. A variable, backtick, or glob still needs an explicit `sh -c '...'`. Its `timeout` defaults to 60 seconds. `send_signal` accepts only 15 (SIGTERM) and 9 (SIGKILL). -- `sb.run_code(...)` requires the exact provider operation: `code.execute` for stateless mode, `code.default-context.execute` for explicit `mode="default-context"`, or `code.context.execute` for a context ID. A template `code` declaration does not implement these operations. Native `alicloud-express` currently refuses interpreter calls; use the supported standard `agent_sandbox.code_interpreter` client for its separate backend contract. +- `sb.run_code(...)` requires the exact provider operation: `code.execute` for stateless mode, `code.default-context.execute` for explicit `mode="default-context"`, or `code.context.execute` for a context ID. An installed interpreter package does not implement these operations. Native `alicloud-express` currently refuses interpreter calls; use the supported standard `agent_sandbox.code_interpreter` client for its separate backend contract. - Files on `sb.files`: `write`, `read`, `read_bytes`, `list`, `exists`, `remove`, `make_dir`, `upload`, `download`. On Express, `sb.files.upload_url` and `sb.files.download_url` return an envd URL that still needs header `X-Access-Token`. A provider that does not declare `files.transfer` raises `E8004`. `sb.upload_url` and `sb.download_url` always refuse. Do not invent a signature-only URL. -- The context manager kills the sandbox. Otherwise call `await sb.kill()`. +- A ProviderSandbox context manager kills the sandbox. For a newly created instance use `kill()` and `close()` in cleanup; for a borrowed connection use only `close()` unless deletion was authorized. - ProviderSandbox defaults to alicloud-express. Use its configured provider transport; do not hardcode a local engine socket or spawn a separate provider implementation. - The only built-in provider is `alicloud-express`. `opensandbox`, `alicloud-container`, `cubesandbox`, and `e2b` are not part of this package. Install them from the catalog with `python -m agent_sandbox.providers install registry: --yes`, then pass that id to `Sandbox.create`. Their notes are in `awesome-providers//docs/README.md`. Native ProviderSandbox reads canonical `ABX_SANDBOX_API_KEY`; only the standard entry maps `E2B_*` settings. @@ -118,18 +126,36 @@ to turn groups on. Without a Dockerfile, `base.image` and `build:` are platform steps; that path is in `references/templates.md`. For `alicloud-express`, write the FC Dockerfile below. +Use strict specification 4. `capabilities` and `tested_on` are retired; installed software does not grant provider operations. This minimal source application follows the current offline fixture: + ```yaml name: my-template version: "1.0.0" -description: "What this sandbox is for" -user: user -workdir: /home/user/app -capabilities: - - shell - - files - - code -ports: - - 9000 +description: "A hello application" +spec_version: 4 +workflow_contract_version: 1 +provides: + app: + protocol: agent-sandbox-server + version: 2 + port: 9000 + operations: [commands.list, commands.run] +default_workflow: application +start_cmd: agent-sandbox-server serve --port 9000 --commands /home/user/app/commands.py +workflows: + application: + kind: application + input: source + startup: exec + service: app + binding: + transport: http + endpoint: provider-port + caller: host + authentication: service-token + operation: commands.run + required_operations: [] + ``` `commands.py` — module-level `@command`, then `start()` only under @@ -168,35 +194,32 @@ if __name__ == "__main__": `alicloud-express` uses the FC base image. Do not add `CMD` or `ENTRYPOINT`. Do not listen on 49983, 5000, or 49999. `` defaults to `cn-hangzhou`. -`` defaults to `v0.0.49` (`ABX_BASE_IMAGE_TAG` overrides it). The platform -starts the server with +`` defaults to `v0.0.49` (`ABX_BASE_IMAGE_TAG` overrides it). Native deploy profiles use the following start command; unified source launch starts the selected application once after creation with its runtime environment: `agent-sandbox-server serve --port 9000 --commands /home/user/app/commands.py`. ```dockerfile FROM fc-e2b-registry..cr.aliyuncs.com/runtime/base: -RUN pip install --no-cache-dir \ - "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" +RUN pip install --no-cache-dir 'agent-sandbox-server==0.3.1a5' WORKDIR /home/user/app COPY commands.py /home/user/app/commands.py EXPOSE 9000 ``` -### Dockerfile for any other provider +### Portable Dockerfile for an author-selected build profile -OpenSandbox and a provider with no `[template]` profile use this image, not the FC image. +The CLI can prepare the supported official native base recipe for both Express and OpenSandbox. Do not automatically substitute this portable recipe: declare a `build_profiles.portable` profile and select it explicitly when appropriate. ```dockerfile FROM python:3.12-slim -RUN pip install --no-cache-dir \ - "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" -WORKDIR /app -COPY commands.py . +RUN pip install --no-cache-dir 'agent-sandbox-server==0.3.1a5' +WORKDIR /home/user/app +COPY commands.py /home/user/app/commands.py EXPOSE 9000 CMD ["python3", "commands.py"] ``` `abx template scaffold` writes this same `commands.py` shape. These Dockerfiles -use a pinned public source archive and do not require a local wheel. CLI build +use the pinned public server package and do not require a local wheel. CLI build may inject an explicitly selected server wheel or resolve its own pinned archive; that preprocessing does not apply to a direct `docker build`. Generation, reserved ports, group policy, and platform steps are in `references/templates.md` next to this file. @@ -237,6 +260,6 @@ Do not upload from a laptop. Do not put a PyPI token in the repo or in chat. 1. Client code imports `agent_sandbox`. `commands.py` imports `agent_sandbox.server` only. 2. Named commands are `@command` and `start()` under `if __name__ == "__main__"`. -3. The default provider's Dockerfile is the FC base image, with no `CMD`. +3. Follow the selected provider/build profile. Do not silently replace an author's Dockerfile; official native placeholders are resolved by the CLI preparation path. 4. Keep native provider configuration on `ABX_*`; standard entry configuration may read `E2B_*`. Never substitute Express credentials for another backend. 5. Do not leak credentials. Do not leave sandboxes running. From 2e5acc4ddbba358e4c710725682664a39dade4ae Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:01:08 +0000 Subject: [PATCH 3/3] docs: complete source template runtime prerequisites --- .../verify/2026-10-24-current-docs-and-records.md | 2 +- agent-sandbox-sdk/SKILL.md | 10 ++++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/.agents/evidence/verify/2026-10-24-current-docs-and-records.md b/.agents/evidence/verify/2026-10-24-current-docs-and-records.md index 2d10c515..49832c83 100644 --- a/.agents/evidence/verify/2026-10-24-current-docs-and-records.md +++ b/.agents/evidence/verify/2026-10-24-current-docs-and-records.md @@ -25,7 +25,7 @@ No new cloud resources or task credentials were created. Existing real-component ## Packaged skill follow-up -Independent review found the two current skills still instructed pre-release source-only installation, and their sample manifest/feature table contradicted the delivered workflow contract. Both now install public alpha 0.3.1a5, preserve standard versus Provider credentials, use an explicitly borrowed application binding, retain valid feature IDs and declare exact consumer operations. The SDK skill's source template uses spec 4; no unsupported host-kit interpreter is invented. Skill references were scanned for the same obsolete installation claims. +Independent review found the two current skills still instructed pre-release source-only installation, and their sample manifest/feature table contradicted the delivered workflow contract. Both now install public alpha 0.3.1a5, preserve standard versus Provider credentials, use an explicitly borrowed application binding, retain valid feature IDs and declare exact consumer operations. The SDK skill's source template uses spec 4 and aligns generation 2, readiness, port and runtime token input with the owning template skeleton; no unsupported host-kit interpreter is invented. Skill references were scanned for the same obsolete installation claims. - PASS: the actual public-a5 `parse_manifest` accepts the complete REST example; `SandboxTemplate.model_validate` accepts the skill's source template. All skill Python blocks parse with `ast.parse`. - Skill changes are instructions only. No image build, new cloud run, first Node package release or new Python package publication is claimed. diff --git a/agent-sandbox-sdk/SKILL.md b/agent-sandbox-sdk/SKILL.md index 515605af..bb584e44 100644 --- a/agent-sandbox-sdk/SKILL.md +++ b/agent-sandbox-sdk/SKILL.md @@ -126,12 +126,16 @@ to turn groups on. Without a Dockerfile, `base.image` and `build:` are platform steps; that path is in `references/templates.md`. For `alicloud-express`, write the FC Dockerfile below. -Use strict specification 4. `capabilities` and `tested_on` are retired; installed software does not grant provider operations. This minimal source application follows the current offline fixture: +Use strict specification 4. `capabilities` and `tested_on` are retired; installed software does not grant provider operations. This minimal source application follows the current [author skeleton](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/_skeleton/template.yaml), including its native generation, readiness probe and runtime token input: ```yaml name: my-template version: "1.0.0" description: "A hello application" +generation: 2 +ports: [9000] +env: + ABX_SERVER_TOKEN: "" spec_version: 4 workflow_contract_version: 1 provides: @@ -142,6 +146,7 @@ provides: operations: [commands.list, commands.run] default_workflow: application start_cmd: agent-sandbox-server serve --port 9000 --commands /home/user/app/commands.py +ready_cmd: agent-sandbox-server healthcheck --port 9000 workflows: application: kind: application @@ -155,9 +160,10 @@ workflows: authentication: service-token operation: commands.run required_operations: [] - ``` +Set `ABX_SERVER_TOKEN` in the launch environment before creating this service-token workflow; the empty manifest value declares runtime input, not a usable secret. Keep credentials out of the manifest and image. + `commands.py` — module-level `@command`, then `start()` only under `if __name__ == "__main__"`. A `start()` call at import time breaks the platform `--commands` import. Do not use `@sandbox.register` or `@registry.command`.