From 4fba782fcb0cf9ce3aaa429072c91f395d051173 Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:01:52 +0000 Subject: [PATCH 1/5] docs: complete ecosystem guidance for unified CLI --- .agents/README.md | 2 + .../2026-11-12-ecosystem-guidance-sync.md | 31 +++++++++ .../2026-11-12-ecosystem-guidance-sync.md | 35 ++++++++++ .github/CONTRIBUTING.md | 6 +- AGENTS.md | 2 +- CHANGELOG.md | 4 ++ .../src/agent_sandbox/providers/installer.py | 2 +- .../src/agent_sandbox/utils/template_index.py | 8 +-- docs/en/DESIGN.md | 6 +- docs/en/README.md | 2 +- docs/en/design/base-image-and-server-sdk.md | 4 +- docs/en/design/mcp-server.md | 56 ++-------------- docs/en/design/repository-layout.md | 2 +- docs/en/design/sdk-api-design.md | 4 +- docs/en/explanation/sandbox-lifecycle.md | 2 +- docs/en/guide/mcp-integration.md | 46 +++++-------- docs/zh/DESIGN.md | 8 +-- docs/zh/README.md | 2 +- docs/zh/design/base-image-and-server-sdk.md | 4 +- docs/zh/design/mcp-server.md | 56 ++-------------- docs/zh/design/sdk-api-design.md | 4 +- docs/zh/explanation/sandbox-lifecycle.md | 2 +- docs/zh/guide/mcp-integration.md | 46 +++++-------- examples/README.md | 2 +- examples/quickstart/README.md | 2 + examples/templates/README.md | 10 +-- examples/templates/python-hello/README.md | 65 ++++--------------- 27 files changed, 170 insertions(+), 243 deletions(-) create mode 100644 .agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md create mode 100644 .agents/notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md diff --git a/.agents/README.md b/.agents/README.md index 629301ae..356724d9 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -275,3 +275,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ - [Community QR replacement](notes/proposed/process/2026-11-10-refresh-community-qr.md) · [verification](evidence/verify/2026-11-10-refresh-community-qr.md). - [SDK simplification mainline reconciliation](evidence/verify/2026-11-10-simplification-main-merge.md). + +- [Python documentation consumers of the unified CLI](notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md) · [verification](evidence/verify/2026-11-12-ecosystem-guidance-sync.md). diff --git a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md new file mode 100644 index 00000000..14baf9a4 --- /dev/null +++ b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md @@ -0,0 +1,31 @@ +# Verification: ecosystem guidance synchronization + +Date: 2026-11-12 +Result: PARTIAL +Baseline: cf3ff7dd14193b63e4fc31cb4a98627c748c5af2 + +## Scope and review + +Update current indexes, fixture guidance, lifecycle examples, authoring ownership and HTTP MCP deployment instructions. The generated HTTP service uses create_mcp_app in a Sandbox with explicit backend runtime credentials and saved application authentication. Correct template-index network-error source-acquisition guidance without changing fetching, caching or SDK execution. + +Command spellings and options were compared with the current parser and built help. Replacing historical result text, adding aliases, modifying runtime algorithms, upgrading template dependencies and recreating cloud resources were excluded after examining whether they were necessary for this task. + +## Results + +Local checks are recorded below. No cloud resources were created. Existing runtime receipts were preserved; modified source identity does not inherit a new qualification. + +## Delivery limitations + +The root dotenv's configured GitHub credential returned HTTP401, no alternate process credential or configured Git credential helper/gh session was available, and private Registry/Website fetches could not authenticate. Public producer main revisions were fetched and checked. Private consumers are based on the latest locally recovered task branches, not claimed current remote main. Finish local commits and reproducible bundles; push, PR, remote CI, review and merge remain blocked until authentication is restored. No new package, image or live website release is claimed. + +## Local verification + +- Remote template-index offline behavior: 35 pytest tests passed, including cache/network-error paths; source-acquisition suggestion follows the current CLI. +- Repository health: 106 passes, one warning, zero failures. +- Lychee 0.24.2 offline with fragments: all 496 tracked Markdown inputs pass. +- Changed source is only an error-guidance string and docstrings; SDK resource execution, dependency pins and runtime behavior were preserved. + +The secret hook initially rejected an environment-variable reference in an MCP +example as a generic quoted secret assignment. The example now uses explicit +YOUR_* placeholders. No secret value was present and the hook was not changed +or bypassed. diff --git a/.agents/notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md b/.agents/notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md new file mode 100644 index 00000000..b72c0907 --- /dev/null +++ b/.agents/notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md @@ -0,0 +1,35 @@ +# Decision: Python documentation consumers of the unified CLI + +Status: proposed + +## Problem + +Unified command changes had landed, but some current examples, contributor text and cross-repository consumers still advertised retired entry points. The user requested complete implementation of the affected ecosystem synchronization. + +## Decision + +Update current indexes, fixture guidance, lifecycle examples, authoring ownership and HTTP MCP deployment instructions. The generated HTTP service uses create_mcp_app in a Sandbox with explicit backend runtime credentials and saved application authentication. Correct template-index network-error source-acquisition guidance without changing fetching, caching or SDK execution. + +## API Design + +No execution API or resource lifecycle change. Command examples follow the current CLI contract. + +## Alternatives considered + +Blind text replacement was rejected: historical runs and version-pinned cases must remain truthful. Rebuilding every template or repeating cloud matrices for documentation would not validate these text changes. Generated consumers must be refreshed from their actual source rather than hand-patched. + +## Dependencies + +Current CLI contract: https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/pull/247. Template producer: https://github.com/Alibaba-Agent-Sandbox/awesome-templates/pull/305. Registry and website consume the reviewed source commits after local validation. + +## Test Strategy + +Run owner document/link/record checks and relevant actual command or catalog checks. Verify generated consumer snapshots through their normal generators and local site builds. Record missing prerequisites and remote authentication failures separately. + +## Acceptance criteria + +Current user instructions resolve to supported commands; every catalog template is checked; historical commands have an explicit version/research boundary. Bilingual pages and generated consumers agree. No secrets, acceptance results or release claims are fabricated. + +## Evidence + +[Verification](../../../evidence/verify/2026-11-12-ecosystem-guidance-sync.md). diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ae3ac4db..560256cd 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -180,9 +180,9 @@ Read the owning repository's [contributor guide](https://github.com/Alibaba-Agen Use the CLI (`abx`, from the `agent-sandbox` repository) to search the remote index: ```bash -abx template search python # search by tag or keyword -abx template search ai-agent # find AI agent templates -abx template search browser # find browser automation templates +abx template list python # search by tag or keyword +abx template list ai-agent # find AI agent templates +abx template list browser # find browser automation templates ``` ## Commit Message Convention diff --git a/AGENTS.md b/AGENTS.md index 187c0840..8c3ff7c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,7 @@ ## Project Overview -**Agent Sandbox** (distribution name `agent-sandbox-client`, import `agent_sandbox`) provides standard synchronous/asynchronous Express clients and the explicit asynchronous `ProviderSandbox` for provider/server extensions. Standard entries follow the pinned Alibaba-supported E2B contract; conditional capabilities still depend on the actual account/function. Launch templates with `abx template launch `; advanced image preparation uses `abx template build|deploy`. Read `docs/en/guide/migrate-from-e2b.md` before changing either surface. +**Agent Sandbox** (distribution name `agent-sandbox-client`, import `agent_sandbox`) provides standard synchronous/asynchronous Express clients and the explicit asynchronous `ProviderSandbox` for provider/server extensions. Standard entries follow the pinned Alibaba-supported E2B contract; conditional capabilities still depend on the actual account/function. Launch templates with `abx deploy --name `; advanced image preparation uses `abx template build/publish`. Read `docs/en/guide/migrate-from-e2b.md` before changing either surface. This repository (`python-sdk`) holds the **Python SDK only**, split into two distributions that share the `agent_sandbox` namespace and are **versioned in lockstep** (same version number): diff --git a/CHANGELOG.md b/CHANGELOG.md index 946ad977..a1db3654 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ## [Unreleased] +### Documentation + +- Synchronize CLI-dependent SDK documentation, HTTP MCP template deployment and source-acquisition error guidance. / 同步 SDK 文档中的 CLI 用法、HTTP MCP 模板部署与源码获取错误指引。 + ### Changed - Align current English and Chinese CLI guides with template authoring, named deployment lifecycle and Provider operations; preserve the SDK’s independent clients and instance methods. diff --git a/client-sdk/src/agent_sandbox/providers/installer.py b/client-sdk/src/agent_sandbox/providers/installer.py index dd5c1b65..e3ff17c6 100644 --- a/client-sdk/src/agent_sandbox/providers/installer.py +++ b/client-sdk/src/agent_sandbox/providers/installer.py @@ -109,7 +109,7 @@ def expand_catalog_ref( ) -> tuple[str, str | None, str | None]: """Turn ``owner/repo//subdir[@ref]`` into a GitHub URL plus subdir and ref. - Same grammar as ``abx template install``: ``//`` is the directory inside the + Same grammar as ``abx template init --from``: ``//`` is the directory inside the repository, ``@`` after that is the git ref. A full git URL, an scp-style ``git@host:path``, or a local path is returned unchanged. ``--ref`` and ``--subdir`` still work; giving both forms with different values is an error. diff --git a/client-sdk/src/agent_sandbox/utils/template_index.py b/client-sdk/src/agent_sandbox/utils/template_index.py index ba7d1aae..8dd50411 100644 --- a/client-sdk/src/agent_sandbox/utils/template_index.py +++ b/client-sdk/src/agent_sandbox/utils/template_index.py @@ -2,8 +2,8 @@ The official and community template catalog lives in a **single source of truth** repository: ``alibaba-agent-sandbox/awesome-templates``. Its root index file -(``awesome-templates.yaml``) is what ``abx template search`` queries and what -``abx template install `` resolves bare template names against. +(``awesome-templates.yaml``) is what ``abx template list`` queries and what +``abx template init DIRECTORY --from `` resolves bare template names against. Design notes ------------ @@ -460,8 +460,8 @@ async def fetch_index( suggestion = ( "Check your network connection, or point at a mirror with " f"--index-url / {INDEX_URL_ENV}. For GitHub rate limits, authenticate " - "with 'abx config set github_token'. As a last resort install directly " - "with 'abx template install owner/repo//subdir[@ref]'." + "with 'abx config set github_token'. As a last resort acquire source directly " + "with 'abx template init ./project --from owner/repo//subdir[@ref]'." ) try: diff --git a/docs/en/DESIGN.md b/docs/en/DESIGN.md index 358ea09a..f1bdda1b 100644 --- a/docs/en/DESIGN.md +++ b/docs/en/DESIGN.md @@ -8,7 +8,7 @@ ## Project Overview -**Agent Sandbox** (`agent-sandbox-client` on PyPI) is a Python SDK for the Alibaba Cloud FC Agent Sandbox service. It is the runtime client: create, use and kill sandboxes. Source templates normally start with `abx template launch`; Python consumes the returned sandbox. Advanced image preparation uses `abx template build` and `abx template deploy`. Method names are E2B-shaped to ease migration; the standard public API follows the pinned Alibaba E2B contract (see [Migrate from E2B](guide/migrate-from-e2b.md)). +**Agent Sandbox** (`agent-sandbox-client` on PyPI) is a Python SDK for the Alibaba Cloud FC Agent Sandbox service. It is the runtime client: create, use and kill sandboxes. Source templates normally start with `abx deploy`; Python consumes the returned sandbox. Advanced image preparation uses `abx template build` and `abx deploy`. Method names are E2B-shaped to ease migration; the standard public API follows the pinned Alibaba E2B contract (see [Migrate from E2B](guide/migrate-from-e2b.md)). This repository holds the Python SDK as two lock-step PyPI distributions — `agent-sandbox-client` (`client-sdk/`, import `agent_sandbox`) and `agent-sandbox-server` (`server-sdk/`, import `agent_sandbox.server`, the container-side runtime). The `abx` CLI is a Node.js/TypeScript project in the `cli` repository, which holds the CLI's own design and guide documents (see [Related: the abx CLI](#related-the-abx-cli)). @@ -126,8 +126,8 @@ Chinese copies of these pages live under `docs/zh/`. `repository-layout.md` is E | SDK core (Sandbox, files, commands, code) | **Implemented** | | | MCP Server (STDIO) | **Implemented** | 7 P0 tools | | MCP Server (Streamable HTTP) | **Implemented** | `mcp_http.py` | -| FC deployment artifact application | **Implemented** | `agent_sandbox.agent.mcp_http:asgi_app`; the artifact is generated by `abx mcp deploy` in the CLI. See [mcp-server.md](design/mcp-server.md#7-fc-deployment) | -| Template startup and image preparation | **In the CLI** | Start sources with `abx template launch` and consume with the SDK; advanced preparation uses `abx template build` and `abx template deploy` | +| Deployable HTTP MCP application | **Implemented** | `create_mcp_app`; the source is generated by `abx template init --template mcp` in the CLI. See [mcp-server.md](design/mcp-server.md#7-deployable-http-mcp) | +| Template startup and image preparation | **In the CLI** | Start sources with `abx deploy` and consume with the SDK; advanced preparation uses `abx template build` and `abx deploy` | | One environment variable per configuration key (SDK) | **Implemented** | See [Configuration](reference/configuration.md); CLI spec in `cli/docs/design/providers-and-credentials-cli.md` | | Provider plugins (SDK, `python -m agent_sandbox.providers`) | **Implemented** | See [Providers](guide/providers.md). The CLI loads installed `node`, `exec` and `rest` plugins (`abx provider`, `abx --provider`) | | Persistent sandbox | **Future** | Requires underlying platform support | diff --git a/docs/en/README.md b/docs/en/README.md index c1939b64..f372e023 100644 --- a/docs/en/README.md +++ b/docs/en/README.md @@ -60,7 +60,7 @@ The installer fetches the catalog index at `https://registry.agent-sandbox.cn/pr | [File and command controls](guide/file-and-command-controls.md) | Limit paths and commands | | [Agents API](guide/agents-api.md) | Codex and Qwen Code HTTP sessions inside the sandbox | | [Hosted agents](guide/hosted-agents.md) | How those routes refuse and what they return | -| [Build and deploy](guide/build-and-deploy.md) | `abx template build` and `abx template deploy` | +| [Build and deploy](guide/build-and-deploy.md) | `abx template build` and `abx deploy` | How a change counts as tested: [Testing and the Definition of Done](guide/testing-e2e.md). diff --git a/docs/en/design/base-image-and-server-sdk.md b/docs/en/design/base-image-and-server-sdk.md index bb929c76..e1f4095b 100644 --- a/docs/en/design/base-image-and-server-sdk.md +++ b/docs/en/design/base-image-and-server-sdk.md @@ -5,7 +5,7 @@ > Product requirement: *all template builds should be based on the Alibaba Cloud Agent Sandbox > (FC Agent Sandbox) base image.* > -> **Update.** The Python client no longer builds images: `Image`, `DockerBuilder`, `Sandbox.deploy` and `agent_sandbox.api.base_image` were removed. The base-image contract in section 3, the lint and the Dockerfile scaffold are owned by the `abx` CLI (`abx template scaffold|build|deploy`). Sections 4, 5, 7 and 8 describe what remains in this repository. +> **Update.** The Python client no longer builds images: `Image`, `DockerBuilder`, `Sandbox.deploy` and `agent_sandbox.api.base_image` were removed. The base-image contract in section 3, the lint and the Dockerfile scaffold are owned by the `abx` CLI (`abx template init/build` and `abx deploy`). Sections 4, 5, 7 and 8 describe what remains in this repository. ## 1. What the base image is (evidence) @@ -91,7 +91,7 @@ Documented in `server-api.md` and enforced by the CLI's template lint: ## 5. CLI-side changes (recorded in `cli-followups.md`) -Node scaffold `abx template scaffold` (FROM official base, scaffold per section 3); deploy path +Node scaffold `abx template init` (FROM official base, scaffold per section 3); deploy path (wheel injection, `envd_inject` auto-choice, `start_cmd`/`ready_cmd`); `template.yaml` `server:` compile; AI template-guide prompt (must start FROM the official base, never override ENTRYPOINT, use `agent-sandbox-server serve`). diff --git a/docs/en/design/mcp-server.md b/docs/en/design/mcp-server.md index 23c0e126..93a6080d 100644 --- a/docs/en/design/mcp-server.md +++ b/docs/en/design/mcp-server.md @@ -291,7 +291,7 @@ graph LR - `GET /health` — health probe returning `{"status": "ok", "protocol": "2025-06-18"}` - **Sessions**: in-process `SessionStore`; idle TTL 3600 s (default), max 100 concurrent sessions (default); capacity exhaustion returns 503 with JSON-RPC error `-32000` - **Version negotiation**: `initialize` echoes the client-requested `protocolVersion` when supported; this transport supports `2025-06-18` only, matching `GET /health`. Missing or unsupported requested versions negotiate to `2025-06-18` — per the MCP spec the server responds with a version it supports, and clients that cannot accept it may disconnect. The STDIO transport independently keeps `2024-11-05` -- **Use case**: remote service, team sharing, multiple clients; deploy to Alibaba Cloud FC via the artifact generated by the CLI's `abx mcp deploy`, or run locally with uvicorn +- **Use case**: remote service, team sharing, multiple clients; create an editable HTTP MCP template with `abx template init --template mcp` and deploy it with `abx deploy`, or run locally with uvicorn - **Optional dependency**: Starlette + uvicorn (`pip install --index-url https://pypi.org/simple 'agent-sandbox-client[mcp]==0.4.0a6'`) ### Authentication @@ -335,7 +335,7 @@ graph TD The Python server is registered in an IDE like any STDIO MCP server. The entry is `python -m agent_sandbox.agent.mcp`; the IDE passes the credentials in `env`. Examples are in Section 6. -The `abx mcp install --target cursor|claude|vscode` (merges an `agent-sandbox` entry into the IDE config), `abx mcp status` (server name, transport, tool list, whether an API key is configured, per-IDE install flags), `abx mcp start|stop` and `abx mcp deploy` commands belong to the Node.js CLI; their design is the CLI's [MCP Server design](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/mcp-server.md). +The `abx mcp install --target cursor|claude|vscode` (merges an `agent-sandbox` entry into the IDE config), `abx mcp status` (server name, transport, tool list, whether an API key is configured, per-IDE install flags), `abx mcp start|stop` commands belong to the Node.js CLI; their design is the CLI's [MCP Server design](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/mcp-server.md). ## 6. Configuration Examples @@ -407,58 +407,14 @@ After deploying the HTTP app (Section 7), point clients at the endpoint; add a B } ``` -## 7. FC Deployment +## 7. Deployable HTTP MCP -> **Status:** `abx mcp deploy` generates a deployment artifact; automatic FC API deployment is **not** implemented. Manual deployment steps are printed after generation. +The CLI generates an editable Sandbox application with `template init --template mcp`. Its app.py calls this SDK's `create_mcp_app`; the manifest, Dockerfile and pinned requirements describe how to run it. Deployment uses the ordinary `deploy/status/delete` lifecycle. See [deploy an HTTP MCP service](../guide/mcp-integration.md#deploy-an-http-mcp-service) for commands and credentials. -### Architecture - -The MCP Server can be deployed to Alibaba Cloud Function Compute (FC) as a Streamable HTTP endpoint, leveraging FC's MCP session affinity routing. - -```mermaid -graph TB - CLI["abx mcp deploy → artifact directory"] - FC["FC function: agent-sandbox-mcp (created manually)"] - Sandbox["Envd sandbox (separate FC instance)"] - - CLI --> FC - FC --> Sandbox - - subgraph FC_Function ["FC function"] - ASGI["app.py → agent_sandbox.agent.mcp_http:asgi_app"] - Trigger["HTTP trigger: POST/GET/DELETE /mcp"] - Session["Session affinity: Mcp-Session-Id"] - Env["Env vars: E2B_API_KEY / ABX_MCP_AUTH_TOKEN / ABX_DEFAULT_TEMPLATE"] - end -``` - -### Deployment Command - -The artifact is generated by `abx mcp deploy` (options, region resolution, token sources); see the CLI's [MCP Server design](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/mcp-server.md#7-fc-deployment) and [CLI Design — mcp deploy](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/cli-design.md). The sections below describe the artifact and the application it runs, which this SDK provides. - -### Artifact Contents - -| File | Content | -|------|---------| -| `requirements.txt` | `agent-sandbox-client[mcp]`, `uvicorn>=0.29` | -| `app.py` | ASGI entry point reading `ABX_MCP_AUTH_TOKEN`, `E2B_API_KEY`, `E2B_API_URL`, `E2B_DOMAIN`, `ABX_DEFAULT_TEMPLATE` from the FC function environment | -| `config.yaml` | YAML deployment manifest (not an FC API payload): `function_name`, `region`, `runtime` (`python3.10`), `handler` (`app.app`), `memory`, `timeout`, `environment_variables`, `http_trigger` (methods POST/GET/DELETE + `enable_session_affinity`), optional `custom_domain` | - -`abx mcp deploy` also prints manual deployment steps (package the artifact, create the function via the FC console or SDK, create an HTTP trigger, enable `Mcp-Session-Id` affinity if supported) and an IDE config template with the Bearer token masked. - -### Key Design Points - -- **Protocol**: Streamable HTTP (MCP spec 2025-06-18); `initialize` negotiates `2025-06-18` consistently with `GET /health` (STDIO keeps `2024-11-05`) -- **Session affinity**: delegated to the FC platform layer via the `Mcp-Session-Id` header — no application-level sticky routing needed -- **Authentication**: dual-layer — client→MCP uses `Authorization: Bearer `; MCP→sandbox uses `E2B_API_KEY` from the FC env -- **Lifecycle**: sandboxes are lazily created per MCP session; `DELETE /mcp` triggers cleanup; the idle-session TTL is the safety net -- **Cold start**: FC cold start (~1–3 s) may conflict with MCP initialize timeouts; provisioned instances are recommended for production -- **Secrets**: `config.yaml` contains the API key and Bearer token — never commit it to version control - -See the [MCP Integration guide](../guide/mcp-integration.md) for end-to-end usage; the full `abx mcp deploy` parameter reference is in the CLI repository (see [Deployment Command](#deployment-command)). +The application runs one process with in-memory MCP sessions. Its public MCP endpoint and the separate sandboxes created by tools have different lifecycles. Keep Provider traffic headers and MCP Bearer authentication, reuse the session header after initialization, and end each session before deleting the service. Service replacement does not persist sessions. --- ## Related: the abx CLI -The Node.js `abx` CLI has its own MCP server implementation and the commands around it: [MCP Server design (CLI)](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/mcp-server.md) (`abx mcp install|start|stop|status|deploy`, tool schemas as implemented in TypeScript, FC deployment) and [CLI Command System](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/cli-design.md). +The Node.js `abx` CLI has its own MCP server implementation and the commands around it: [MCP Server design (CLI)](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/mcp-server.md) (`abx mcp install|start|stop|status`, tool schemas as implemented in TypeScript, FC deployment) and [CLI Command System](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/cli-design.md). diff --git a/docs/en/design/repository-layout.md b/docs/en/design/repository-layout.md index 8d1c6777..80e0a1ca 100644 --- a/docs/en/design/repository-layout.md +++ b/docs/en/design/repository-layout.md @@ -155,7 +155,7 @@ links with an absolute URL; byte-identical copies are forbidden (checked by the |----------------|-------|------------| | `reference/template-yaml-spec`, `reference/error-codes` (E1xxx-E6xxx taxonomy), `reference/server-http-api`, `design/server-api`, `design/template-system` (schema half) | **python-sdk** | CLI links (CLI keeps only CLI-specific codes such as `E2007` and the exit-code map) | | `guide/getting-started`, `guide/authentication`, `guide/environment-variables`, `guide/troubleshooting`, `reference/configuration`, `guide/mcp-integration` | **each repo owns its own, trimmed version** (SDK: Python API, `sandbox_api_key=`, `ProviderSandbox`; CLI: `abx config`, flags, exit codes). The shared credential precedence table is authored once in python-sdk `reference/configuration` and linked from the CLI page | no duplicated sections | -| `guide/authoring-templates` | **cli** (workflow: `abx template scaffold/deploy`) with a link to python-sdk `guide/server-sdk` for the `commands.py` API | link | +| `guide/authoring-templates` | **cli** (workflow: `abx template init` → `abx deploy`) with a link to python-sdk `guide/server-sdk` for the `commands.py` API | link | | `design/mcp-server` | **python-sdk** (`agent_sandbox.agent.mcp`) | CLI documents `abx mcp install` and links | | `DESIGN.md`, `README.md` indexes | each repo, listing only its own pages plus a "Related documentation" section | link | diff --git a/docs/en/design/sdk-api-design.md b/docs/en/design/sdk-api-design.md index 40ace513..42f5a7c7 100644 --- a/docs/en/design/sdk-api-design.md +++ b/docs/en/design/sdk-api-design.md @@ -8,7 +8,7 @@ It is a current overview, not a proposal for additional APIs. ## Design rules - ProviderSandbox creates and operates sandboxes. Source image preparation belongs - to the CLI: normally `abx template launch `, with build/deploy as + to the CLI: normally `abx deploy --name `, with build/deploy as advanced operations. Standard Template builders retain their separate contract. - Shell commands, interpreter execution and template application commands use distinct APIs and prerequisites. Creating `base` does not start an application. @@ -64,7 +64,7 @@ not create a new platform capability. | Registered application command | Application client's `commands.run(...)` | Running SandboxServer service and its application token | | Registered command discovery | Application client's `commands.list()` | The same running service | -First launch the entire template with `abx template launch `. Connect +First launch the entire template with `abx deploy --name `. Connect using the returned sandbox information and `application_client(..., token=...)` so provider gateway headers and application authentication are preserved. See [template launch](../guide/template-workflows.md) and diff --git a/docs/en/explanation/sandbox-lifecycle.md b/docs/en/explanation/sandbox-lifecycle.md index 92de627a..c8abe2fa 100644 --- a/docs/en/explanation/sandbox-lifecycle.md +++ b/docs/en/explanation/sandbox-lifecycle.md @@ -92,7 +92,7 @@ result = await sandbox.run_code("code", timeout=60) abx --timeout 600 create # Command-level timeout -abx exec sbx-xxxx "command" --timeout 120 +abx sandbox exec sbx-xxxx "command" --timeout 120 ``` --- diff --git a/docs/en/guide/mcp-integration.md b/docs/en/guide/mcp-integration.md index 10d2c1c0..973f4ff4 100644 --- a/docs/en/guide/mcp-integration.md +++ b/docs/en/guide/mcp-integration.md @@ -137,9 +137,9 @@ Authorization: Bearer - Loopback with the token unset → authentication disabled, and the process warns - Token set but empty → **fails closed**: every request is rejected with 401 -- FC artifact with the token unset or empty → the process refuses to start +- generated HTTP service with the token unset or empty → the process refuses to start -Tokens are compared with constant-time comparison. Generate one with `openssl rand -base64 32`. The CLI's `abx mcp start --http` (`--auth-token`) and `abx mcp deploy --generate-token` accept or generate one for you; see [Related: the abx CLI](#related-the-abx-cli). +Tokens are compared with constant-time comparison. Generate one with `openssl rand -base64 32`. The CLI's `abx mcp start --http` (`--auth-token`) accepts a token; generated MCP templates use the saved application token by default; see [Related: the abx CLI](#related-the-abx-cli). ### Client Configuration (Remote) @@ -158,34 +158,24 @@ Tokens are compared with constant-time comparison. Generate one with `openssl ra --- -## FC Deployment Artifact +## Deploy an HTTP MCP service -The deployment artifact for Alibaba Cloud Function Compute is generated by the `abx mcp deploy` command (see [Related: the abx CLI](#related-the-abx-cli)); the generated Python application is what this SDK provides. It does **not** call the FC API — you create the function manually via the console or SDK. +Use the [current source CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox#installation) to create editable source and deploy it as a Sandbox application: -The artifact directory contains: - -| File | Content | -|------|---------| -| `requirements.txt` | `agent-sandbox-client[mcp]`, `uvicorn>=0.29` | -| `app.py` | ASGI entry point reading FC env vars (`ABX_MCP_AUTH_TOKEN`, `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL`, `ABX_SANDBOX_DOMAIN`, `ABX_DEFAULT_TEMPLATE`) | -| `config.yaml` | YAML manifest with function name, region, runtime `python3.10`, handler `app.app`, memory/timeout, env vars, HTTP trigger (POST/GET/DELETE), session affinity | - -The deployment steps are: package → create function → create HTTP trigger → enable `Mcp-Session-Id` affinity if supported. +```bash +abx template init ./mcp-service --template mcp +abx deploy ./mcp-service --name mcp-service \ + -e 'ABX_SANDBOX_API_KEY=' \ + -e 'ABX_SANDBOX_BASE_URL=' \ + -e 'ABX_SANDBOX_DOMAIN=' +abx status mcp-service +``` -> **Security**: `config.yaml` contains your API key and Bearer token. Do not commit it to version control. +The generated `app.py` calls `create_mcp_app`; `template.yaml`, Dockerfile and pinned `requirements.txt` describe its runtime. Supply the Sandbox API key, API URL and domain for the same account and region: these configure the sandboxes created by the MCP tools. Build credentials serve a different purpose. -After deployment, configure clients with the trigger URL: +The CLI generates and saves `ABX_SERVER_TOKEN` when needed. The generated service uses it as the MCP Bearer token unless `ABX_MCP_AUTH_TOKEN` is explicitly supplied. Append `/mcp` to the returned MCP service URL, preserve Provider endpoint headers and configure `Authorization: Bearer ` in the client. Provider traffic authentication remains separate. -```json -{ - "mcpServers": { - "agent-sandbox-remote": { - "url": "https:///mcp", - "headers": { "Authorization": "Bearer " } - } - } -} -``` +Reuse `Mcp-Session-Id` after initialization. The application keeps sessions in one process; replacement loses in-memory sessions. `DELETE /mcp` closes an MCP session and cleans its owned sandboxes. After ending sessions, remove the service with `abx delete mcp-service --yes`. See the CLI [MCP guide](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/mcp-integration.md) for the complete deployment and client workflow. ## Usage Examples @@ -249,7 +239,7 @@ curl -s -X DELETE http://localhost:9000/mcp \ | IDE shows the server as failed / no tools | `python` on the IDE's `PATH` is not the interpreter that has `agent-sandbox` installed | Use an absolute interpreter path in the IDE config's `command` | | Tools list works but every call errors | API key missing or invalid | Set `ABX_SANDBOX_API_KEY` in the server's `env` block | | `create_sandbox` fails after IDE restart | Backend API URL/region mismatch | Set `ABX_SANDBOX_BASE_URL` in the server's `env` block | -| HTTP 401 on every request | Empty `ABX_MCP_AUTH_TOKEN` (fails closed) | Set a non-empty token. A local loopback server can omit the variable to disable auth. The FC artifact will not start without a token | +| HTTP 401 on every request | Empty `ABX_MCP_AUTH_TOKEN` (fails closed) | Set a non-empty token. A local loopback server can omit the variable to disable auth. The generated HTTP service will not start without a token | | HTTP 404 Unknown session | `Mcp-Session-Id` expired (idle TTL 3600 s) or instance restarted | Re-send `initialize` to create a new session | | HTTP 503 session limit | More than 100 concurrent sessions in the process | Close idle sessions (`DELETE /mcp`) or raise `max_sessions` via `create_mcp_app()` | | HTTP 405 on `GET /mcp` | SSE notifications not implemented | Expected — use `POST /mcp` only | @@ -260,7 +250,7 @@ Problems specific to the CLI server (`abx` not on the IDE's `PATH`, `abx mcp sta - **Transport protocols**: STDIO (newline-delimited JSON-RPC 2.0, protocol version 2024-11-05) and Streamable HTTP (spec 2025-06-18). `initialize` negotiates each transport's supported version — a supported requested `protocolVersion` is echoed back; missing or unsupported requests fall back to the transport's own version (so HTTP health and initialize both report 2025-06-18) - **Sandbox management**: the server internally maintains a `SandboxManager` per session that manages the lifecycle of multiple sandbox instances -- **Default template**: `base` for the Python STDIO server, the HTTP app and `abx mcp deploy` artifacts (the CLI's own `abx mcp start` uses `code-interpreter-v1`). `create_sandbox` uses that server template when `template` is omitted +- **Default template**: `base` for the Python STDIO server, the HTTP app and generated MCP templates (the CLI's own `abx mcp start` uses `code-interpreter-v1`). `create_sandbox` uses that server template when `template` is omitted - **STDIO**: one message may be up to 8 MiB. A longer line is rejected and the process keeps serving. `ping` is answered while a tool call is still running - **HTTP sessions**: idle TTL 3600 s, max 100 concurrent sessions per process, capacity exhaustion returns 503 @@ -275,4 +265,4 @@ Problems specific to the CLI server (`abx` not on the IDE's `PATH`, `abx mcp sta ## Related: the abx CLI -The Node.js `abx` CLI provides its own MCP server and the commands around it. They are documented in the CLI repository: [MCP Integration (CLI)](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/guide/mcp-integration.md) (`abx mcp install|start|stop|status|deploy`, IDE install targets, background HTTP mode, pid and log files) and the CLI's [MCP Server design](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/mcp-server.md). +The Node.js `abx` CLI provides its own MCP server and the commands around it. They are documented in the CLI repository: [MCP Integration (CLI)](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/guide/mcp-integration.md) (`abx mcp install|start|stop|status`, IDE install targets, background HTTP mode, pid and log files) and the CLI's [MCP Server design](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/en/design/mcp-server.md). diff --git a/docs/zh/DESIGN.md b/docs/zh/DESIGN.md index 41b931b0..132198c4 100644 --- a/docs/zh/DESIGN.md +++ b/docs/zh/DESIGN.md @@ -8,7 +8,7 @@ ## 项目概述 -**Agent Sandbox**（PyPI 包名 `agent-sandbox-client`）是面向阿里云 FC Agent 沙箱服务的 Python SDK。它是运行时客户端：创建、使用、销毁沙箱；源码模板通常用 `abx template launch` 启动，再由 Python 连接返回的沙箱；高级镜像准备使用 `abx template build` 与 `abx template deploy`。方法名参考了 E2B，方便迁移，标准公开接口遵循阿里云支持的 E2B 行为契约（见[从 E2B 迁移](guide/migrate-from-e2b.md)）。 +**Agent Sandbox**（PyPI 包名 `agent-sandbox-client`）是面向阿里云 FC Agent 沙箱服务的 Python SDK。它是运行时客户端：创建、使用、销毁沙箱；源码模板通常用 `abx deploy` 启动，再由 Python 连接返回的沙箱；高级镜像准备使用 `abx template build` 与 `abx deploy`。方法名参考了 E2B，方便迁移，标准公开接口遵循阿里云支持的 E2B 行为契约（见[从 E2B 迁移](guide/migrate-from-e2b.md)）。 本仓库包含 Python SDK，以两个版本同步发布的 PyPI 分发包提供——`agent-sandbox-client`（`client-sdk/`，导入 `agent_sandbox`）与 `agent-sandbox-server`（`server-sdk/`，导入 `agent_sandbox.server`，容器侧运行时）。`abx` CLI 是 `cli` 仓库中的 Node.js/TypeScript 项目，CLI 自己的设计与指南文档也在该仓库（见[相关：abx CLI](#相关abx-cli)）。 @@ -90,7 +90,7 @@ graph TB | 专题 | 文档 | 摘要 | |------|------|------| -| **MCP Server** | [mcp-server.md](design/mcp-server.md) | 7 个 P0 工具、STDIO 与 Streamable HTTP 传输、FC 部署产物、会话绑定 | +| **MCP Server** | [mcp-server.md](design/mcp-server.md) | Python 工具、STDIO 与 Streamable HTTP 传输、可编辑服务模板和会话归属 | | **Agents API** | [guide/agents-api.md](guide/agents-api.md) | 在沙箱里运行 Agent 的唯一方式：`/v1/agents/**`。基础镜像不预装 CLI | ### 服务器与基础设施 @@ -126,8 +126,8 @@ graph TB | SDK 核心（Sandbox、文件、命令、代码） | **已实现** | | | MCP Server（STDIO） | **已实现** | 7 个 P0 工具 | | MCP Server（Streamable HTTP） | **已实现** | `mcp_http.py` | -| FC 部署产物应用 | **已实现** | `agent_sandbox.agent.mcp_http:asgi_app`；产物由 CLI 的 `abx mcp deploy` 生成。见 [mcp-server.md](design/mcp-server.md#7-fc-部署) | -| 模板启动与镜像准备 | **在 CLI 中** | 使用 `abx template launch` 启动源码，再由 SDK 连接；高级镜像准备使用 `abx template build` 与 `abx template deploy` | +| 可部署的 HTTP MCP 应用 | **已实现** | `create_mcp_app`；源码由 CLI 的 `abx template init --template mcp` 生成。见 [mcp-server.md](design/mcp-server.md#7-可部署的-http-mcp) | +| 模板启动与镜像准备 | **在 CLI 中** | 使用 `abx deploy` 启动源码，再由 SDK 连接；高级镜像准备使用 `abx template build` 与 `abx deploy` | | 每个配置键一个环境变量（SDK） | **已实现** | 见[配置参考](reference/configuration.md)；CLI 规格见 `cli/docs/zh/design/providers-and-credentials-cli.md` | | 提供方插件（SDK，`python -m agent_sandbox.providers`） | **已实现** | 见[提供方](guide/providers.md)。CLI 加载已安装的 `node`、`exec` 和 `rest` 插件（`abx provider`、`abx --provider`） | | 持久沙箱 | **远期** | 需底层平台支持 | diff --git a/docs/zh/README.md b/docs/zh/README.md index 707f0a3a..36c81b1e 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -60,7 +60,7 @@ Agent Sandbox 是可切换提供方的沙箱 SDK。默认提供方是阿里云 | [文件与命令控制](guide/file-and-command-controls.md) | 限制路径和命令 | | [Agents API](guide/agents-api.md) | 沙箱里的 Codex 与 Qwen Code HTTP 会话 | | [托管代理](guide/hosted-agents.md) | 这些路由的拒绝和响应 | -| [构建与部署](guide/build-and-deploy.md) | `abx template build` 与 `abx template deploy` | +| [构建与部署](guide/build-and-deploy.md) | `abx template build` 与 `abx deploy` | 测试如何算完成，见[测试与完成定义](guide/testing-e2e.md)。 diff --git a/docs/zh/design/base-image-and-server-sdk.md b/docs/zh/design/base-image-and-server-sdk.md index 19423d9b..d9a1f4b1 100644 --- a/docs/zh/design/base-image-and-server-sdk.md +++ b/docs/zh/design/base-image-and-server-sdk.md @@ -4,7 +4,7 @@ > [fine-grained-capabilities-review.md](../archive/fine-grained-capabilities-review.md)。 > 产品要求：*所有模板构建都应基于阿里云 Agent Sandbox（FC Agent Sandbox）基础镜像。* > -> **更新。** Python 客户端不再构建镜像：`Image`、`DockerBuilder`、`Sandbox.deploy` 和 `agent_sandbox.api.base_image` 都已删除。第 3 节的基础镜像契约、lint 和 Dockerfile 脚手架归 `abx` CLI（`abx template scaffold|build|deploy`）。第 4、5、7、8 节描述这个仓库里留下的部分。 +> **更新。** Python 客户端不再构建镜像：`Image`、`DockerBuilder`、`Sandbox.deploy` 和 `agent_sandbox.api.base_image` 都已删除。第 3 节的基础镜像契约、lint 和 Dockerfile 脚手架归 `abx` CLI（`abx template init/build` 与 `abx deploy`）。第 4、5、7、8 节描述这个仓库里留下的部分。 > 英文版为准：[../../en/design/base-image-and-server-sdk.md](../../en/design/base-image-and-server-sdk.md)。 ## 1. 基础镜像是什么（证据） @@ -77,7 +77,7 @@ ## 5. CLI 侧变更（记录在 `cli-followups.md`） -Node 脚手架 `abx template scaffold`（FROM 官方基础镜像，按第 3 节生成脚手架）；部署路径（wheel 注入、`envd_inject` 自动选择、`start_cmd`/`ready_cmd`）； +Node 脚手架 `abx template init`（FROM 官方基础镜像，按第 3 节生成脚手架）；部署路径（wheel 注入、`envd_inject` 自动选择、`start_cmd`/`ready_cmd`）； `template.yaml` 的 `server:` 编译；AI 模板指南提示词（必须 FROM 官方基础镜像，不得覆盖 ENTRYPOINT，使用 `agent-sandbox-server serve`）。 ## 6. 未决问题（无法从仓库/文档确定） diff --git a/docs/zh/design/mcp-server.md b/docs/zh/design/mcp-server.md index 19186d2a..3d8a90ae 100644 --- a/docs/zh/design/mcp-server.md +++ b/docs/zh/design/mcp-server.md @@ -291,7 +291,7 @@ graph LR - `GET /health` — 健康检查，返回 `{"status": "ok", "protocol": "2025-06-18"}` - **会话**：进程内 `SessionStore`；空闲 TTL 默认 3600 秒、并发会话上限默认 100；容量满时返回 503 与 JSON-RPC 错误 `-32000` - **版本协商**：`initialize` 在请求版本受支持时原样回显；本传输仅支持 `2025-06-18`，与 `GET /health` 一致。请求缺失或不支持的版本时协商到 `2025-06-18` —— 按 MCP 规范，服务器回复自己支持的版本，无法接受的客户端可自行断开。STDIO 传输独立保持 `2024-11-05` -- **适用场景**：远程服务、团队共享、多客户端；用 CLI 的 `abx mcp deploy` 生成的产物部署到阿里云 FC，或本地以 uvicorn 运行 +- **适用场景**：远程服务、团队共享、多客户端；用 CLI 的 `abx template init --template mcp` 生成可编辑模板，再通过 `abx deploy` 部署，或本地以 uvicorn 运行 - **可选依赖**：Starlette + uvicorn（`pip install --index-url https://pypi.org/simple 'agent-sandbox-client[mcp]==0.4.0a6'`） ### 认证 @@ -335,7 +335,7 @@ graph TD Python server 与任何 STDIO MCP server 一样注册到 IDE。入口是 `python -m agent_sandbox.agent.mcp`；IDE 通过 `env` 传入凭证。示例见第 6 节。 -`abx mcp install --target cursor|claude|vscode`（把 `agent-sandbox` 条目合并进 IDE 配置）、`abx mcp status`（server 名称、传输方式、工具列表、API key 是否已配置、各 IDE 的安装状态）、`abx mcp start|stop` 与 `abx mcp deploy` 命令属于 Node.js CLI；其设计见 CLI 的 [MCP Server 设计](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/mcp-server.md)。 +`abx mcp install --target cursor|claude|vscode`（把 `agent-sandbox` 条目合并进 IDE 配置）、`abx mcp status`（server 名称、传输方式、工具列表、API key 是否已配置、各 IDE 的安装状态）、`abx mcp start|stop` 命令属于 Node.js CLI；其设计见 CLI 的 [MCP Server 设计](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/mcp-server.md)。 ## 6. 配置示例 @@ -407,58 +407,14 @@ CLI 的 `abx mcp install` 会写入等价条目，其 `command` 为 `abx`，`arg } ``` -## 7. FC 部署 +## 7. 可部署的 HTTP MCP -> **状态：** `abx mcp deploy` 生成部署产物；自动调用 FC 部署 API **尚未实现**。生成后会打印手动部署步骤。 +CLI 通过 `template init --template mcp` 生成可编辑的沙箱应用。app.py 调用本 SDK 的 `create_mcp_app`；清单、Dockerfile 与固定版本的 requirements 描述运行方式。部署使用普通的 `deploy/status/delete` 生命周期，命令和凭据说明见[部署 HTTP MCP 服务](../guide/mcp-integration.md#部署-http-mcp-服务)。 -### 架构 - -MCP Server 可部署到阿里云函数计算 (FC) 作为 Streamable HTTP 端点，利用 FC 原生的 MCP 会话亲和路由。 - -```mermaid -graph TB - CLI["abx mcp deploy → 产物目录"] - FC["FC 函数: agent-sandbox-mcp（手动创建）"] - Sandbox["Envd 沙箱（另一个 FC 实例）"] - - CLI --> FC - FC --> Sandbox - - subgraph FC_Function ["FC 函数"] - ASGI["app.py → agent_sandbox.agent.mcp_http:asgi_app"] - Trigger["HTTP 触发器: POST/GET/DELETE /mcp"] - Session["会话亲和: Mcp-Session-Id"] - Env["环境变量: E2B_API_KEY / ABX_MCP_AUTH_TOKEN / ABX_DEFAULT_TEMPLATE"] - end -``` - -### 部署命令 - -产物由 `abx mcp deploy` 生成（选项、区域解析、token 来源）；见 CLI 的 [MCP Server 设计](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/mcp-server.md#7-fc-部署) 与 [CLI 设计 — mcp deploy](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/cli-design.md)。以下各节描述产物及其运行的应用，二者由本 SDK 提供。 - -### 产物内容 - -| 文件 | 内容 | -|------|------| -| `requirements.txt` | `agent-sandbox-client[mcp]`、`uvicorn>=0.29` | -| `app.py` | ASGI 入口，从 FC 函数环境变量读取 `ABX_MCP_AUTH_TOKEN`、`E2B_API_KEY`、`E2B_API_URL`、`E2B_DOMAIN`、`ABX_DEFAULT_TEMPLATE` | -| `config.yaml` | YAML 部署清单（非 FC API 载荷）：`function_name`、`region`、`runtime`（`python3.10`）、`handler`（`app.app`）、`memory`、`timeout`、`environment_variables`、`http_trigger`（POST/GET/DELETE 方法 + `enable_session_affinity`）、可选 `custom_domain` | - -`abx mcp deploy` 还会打印手动部署步骤（打包产物、经 FC 控制台或 SDK 创建函数、创建 HTTP 触发器、如支持则启用 `Mcp-Session-Id` 亲和）以及 Bearer token 打码的 IDE 配置模板。 - -### 关键设计要点 - -- **协议**：Streamable HTTP（MCP 规范 2025-06-18）；`initialize` 协商 `2025-06-18`，与 `GET /health` 一致（STDIO 独立保持 `2024-11-05`） -- **会话亲和**：委托 FC 平台层通过 `Mcp-Session-Id` 头实现 — 无需应用层粘性路由 -- **认证**：双层 — 客户端→MCP 使用 `Authorization: Bearer `；MCP→沙箱使用 FC 环境变量中的 `E2B_API_KEY` -- **生命周期**：沙箱按 MCP 会话懒创建；`DELETE /mcp` 触发清理；空闲会话 TTL 作为安全网 -- **冷启动**：FC 冷启动 (~1–3s) 可能与 MCP initialize 超时冲突；生产环境建议使用预留实例 -- **密钥**：`config.yaml` 含 API key 与 Bearer token — 切勿提交到版本控制 - -详见 [MCP 集成指南](../guide/mcp-integration.md) 获取端到端用法；`abx mcp deploy` 的完整参数参考在 CLI 仓库（见[部署命令](#部署命令)）。 +应用在单进程内保存 MCP 会话。MCP 公开入口与工具创建的独立沙箱具有不同生命周期。访问时保留 Provider 流量认证头及 MCP Bearer 认证，初始化后复用会话头，结束会话后再删除服务。替换服务不会保留内存会话。 --- ## 相关：abx CLI -Node.js `abx` CLI 有自己的 MCP server 实现及相关命令：[MCP Server 设计（CLI）](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/mcp-server.md)（`abx mcp install|start|stop|status|deploy`、TypeScript 实现的工具 schema、FC 部署）和 [CLI 命令体系](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/cli-design.md)。 +Node.js `abx` CLI 有自己的 MCP server 实现及相关命令：[MCP Server 设计（CLI）](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/mcp-server.md)（`abx mcp install|start|stop|status`、TypeScript 实现的工具 schema、FC 部署）和 [CLI 命令体系](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/cli-design.md)。 diff --git a/docs/zh/design/sdk-api-design.md b/docs/zh/design/sdk-api-design.md index 34d1ab45..355a3e86 100644 --- a/docs/zh/design/sdk-api-design.md +++ b/docs/zh/design/sdk-api-design.md @@ -7,7 +7,7 @@ ## 设计原则 - ProviderSandbox 创建、操作沙箱。源码镜像准备属于 CLI：通常使用 - `abx template launch `；build/deploy 是高级操作。标准 Template 构建器 + `abx deploy --name `；build/deploy 是高级操作。标准 Template 构建器 保留其独立接口约定。 - Shell 命令、解释器执行和模板应用命令有不同入口与前提。创建 `base` 不会启动应用。 - Provider 声明和真实账号决定可用操作；有同名方法不代表所有平台都实现了它。 @@ -56,7 +56,7 @@ SandboxServer 可通过已有 `@sandbox.register` 或 server 命令注册机制 | 注册的应用命令 | 应用客户端 `commands.run(...)` | 运行中的 SandboxServer 服务及应用令牌 | | 注册命令发现 | 应用客户端 `commands.list()` | 同一运行中的服务 | -先用 `abx template launch ` 启动完整模板，再根据返回的沙箱信息，通过 +先用 `abx deploy --name ` 启动完整模板，再根据返回的沙箱信息，通过 `application_client(..., token=...)` 保留 Provider 网关头和应用认证。见 [模板启动](../guide/template-workflows.md)与[模板 server API](../guide/template-server-api.md)。 仅用熟悉的模板名创建普通平台沙箱，不会执行这一启动流程。 diff --git a/docs/zh/explanation/sandbox-lifecycle.md b/docs/zh/explanation/sandbox-lifecycle.md index b380c5fd..e05915ac 100644 --- a/docs/zh/explanation/sandbox-lifecycle.md +++ b/docs/zh/explanation/sandbox-lifecycle.md @@ -92,7 +92,7 @@ result = await sandbox.run_code("code", timeout=60) abx --timeout 600 create # 命令级超时 -abx exec sbx-xxxx "command" --timeout 120 +abx sandbox exec sbx-xxxx "command" --timeout 120 ``` --- diff --git a/docs/zh/guide/mcp-integration.md b/docs/zh/guide/mcp-integration.md index d607964b..04293829 100644 --- a/docs/zh/guide/mcp-integration.md +++ b/docs/zh/guide/mcp-integration.md @@ -136,9 +136,9 @@ Authorization: Bearer - 回环地址且未设置 token → 认证关闭，进程会警告 - token 已设置但为空 → **fail-closed**：所有请求被拒绝并返回 401 -- FC 产物 token 未设置或为空 → 进程拒绝启动 +- 生成的 HTTP 服务 token 未设置或为空 → 进程拒绝启动 -token 比较使用常量时间算法。可用 `openssl rand -base64 32` 生成。CLI 的 `abx mcp start --http`（`--auth-token`）与 `abx mcp deploy --generate-token` 可接受或为你生成 token；见[相关：abx CLI](#相关abx-cli)。 +token 比较使用常量时间算法。可用 `openssl rand -base64 32` 生成。CLI 的 `abx mcp start --http`（`--auth-token`）接受指定 token；生成的 MCP 模板默认使用本机保存的应用令牌；见[相关：abx CLI](#相关abx-cli)。 ### 客户端配置（远程） @@ -157,34 +157,24 @@ token 比较使用常量时间算法。可用 `openssl rand -base64 32` 生成 --- -## FC 部署产物 +## 部署 HTTP MCP 服务 -阿里云函数计算的部署产物由 `abx mcp deploy` 命令生成（见[相关：abx CLI](#相关abx-cli)）；生成的 Python 应用由本 SDK 提供。它**不**调用 FC API —— 需要通过控制台或 SDK 手动创建函数。 +安装[当前源码 CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox#installation)，生成可编辑源码并部署为沙箱应用： -产物目录包含： - -| 文件 | 内容 | -|------|------| -| `requirements.txt` | `agent-sandbox-client[mcp]`、`uvicorn>=0.29` | -| `app.py` | ASGI 入口，读取 FC 环境变量（`ABX_MCP_AUTH_TOKEN`、`ABX_SANDBOX_API_KEY`、`ABX_SANDBOX_BASE_URL`、`ABX_SANDBOX_DOMAIN`、`ABX_DEFAULT_TEMPLATE`） | -| `config.yaml` | YAML 清单：函数名、地域、运行时 `python3.10`、handler `app.app`、内存/超时、环境变量、HTTP 触发器（POST/GET/DELETE）、会话亲和 | - -部署步骤：打包 → 创建函数 → 创建 HTTP 触发器 → 若支持则启用 `Mcp-Session-Id` 亲和。 +```bash +abx template init ./mcp-service --template mcp +abx deploy ./mcp-service --name mcp-service \ + -e 'ABX_SANDBOX_API_KEY=' \ + -e 'ABX_SANDBOX_BASE_URL=' \ + -e 'ABX_SANDBOX_DOMAIN=' +abx status mcp-service +``` -> **安全**：`config.yaml` 含有 API key 与 Bearer token，请勿提交到版本控制。 +生成的 `app.py` 调用 `create_mcp_app`；`template.yaml`、Dockerfile 和固定版本的 `requirements.txt` 描述运行方式。沙箱 API Key、API URL、domain 需属于同一账号和地域，用于 MCP 工具创建的沙箱，与构建凭据分开配置。 -部署后用触发器 URL 配置客户端： +CLI 按需生成并在本机保存 `ABX_SERVER_TOKEN`。生成的服务默认将它作为 MCP Bearer 令牌；显式提供 `ABX_MCP_AUTH_TOKEN` 时使用后者。在返回的 MCP 服务 URL 后追加 `/mcp`，保留 Provider endpoint 的认证头，并为客户端设置 `Authorization: Bearer `。Provider 流量认证是独立的一层。 -```json -{ - "mcpServers": { - "agent-sandbox-remote": { - "url": "https:///mcp", - "headers": { "Authorization": "Bearer " } - } - } -} -``` +初始化后复用 `Mcp-Session-Id`。应用在单进程内保存会话，替换实例会丢失内存会话。`DELETE /mcp` 结束会话并清理其拥有的沙箱；结束会话后使用 `abx delete mcp-service --yes` 删除服务。完整部署与客户端操作见 CLI [MCP 指南](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/zh/guide/mcp-integration.md)。 ## 场景示例 @@ -248,7 +238,7 @@ curl -s -X DELETE http://localhost:9000/mcp \ | IDE 显示 server 失败 / 无工具 | IDE `PATH` 中的 `python` 不是安装了 `agent-sandbox` 的解释器 | 在 IDE 配置的 `command` 中使用解释器的绝对路径 | | 工具列表正常但每次调用报错 | API key 缺失或无效 | 在 server 的 `env` 块中设置 `ABX_SANDBOX_API_KEY` | | IDE 重启后 `create_sandbox` 失败 | 后端 API URL/地域不匹配 | 在 server 的 `env` 块中设置 `ABX_SANDBOX_BASE_URL` | -| HTTP 每个请求都 401 | `ABX_MCP_AUTH_TOKEN` 为空（fail-closed） | 设置非空 token。本机回环可以删掉该变量来关闭认证。FC 产物没有 token 时不会启动 | +| HTTP 每个请求都 401 | `ABX_MCP_AUTH_TOKEN` 为空（fail-closed） | 设置非空 token。本机回环可以删掉该变量来关闭认证。生成的 HTTP 服务没有 token 时不会启动 | | HTTP 404 Unknown session | `Mcp-Session-Id` 已过期（空闲 TTL 3600 秒）或实例重启 | 重新发送 `initialize` 创建新会话 | | HTTP 503 会话上限 | 进程内并发会话超过 100 | 关闭空闲会话（`DELETE /mcp`）或经 `create_mcp_app()` 调高 `max_sessions` | | `GET /mcp` 返回 405 | SSE 通知尚未实现 | 预期行为 — 只使用 `POST /mcp` | @@ -259,7 +249,7 @@ CLI server 特有的问题（`abx` 不在 IDE 的 `PATH`、`abx mcp status`） - **传输协议**：STDIO（换行分隔 JSON-RPC 2.0，协议版本 2024-11-05）与 Streamable HTTP（规范 2025-06-18）。`initialize` 按 transport 协商支持版本 —— 请求版本受支持时原样回显，缺失或不支持时回退到该 transport 自己的版本（因此 HTTP 的 /health 与 initialize 均报告 2025-06-18） - **沙箱管理**：MCP Server 为每个会话内部维护 `SandboxManager`，管理多个沙箱实例的生命周期 -- **默认模板**：Python STDIO server、HTTP 应用与 `abx mcp deploy` 产物为 `base`（CLI 自己的 `abx mcp start` 使用 `code-interpreter-v1`）。`create_sandbox` 省略 `template` 时用的就是这个 server 模板 +- **默认模板**：Python STDIO server、HTTP 应用与生成的 MCP 模板为 `base`（CLI 自己的 `abx mcp start` 使用 `code-interpreter-v1`）。`create_sandbox` 省略 `template` 时用的就是这个 server 模板 - **STDIO**：单条消息上限 8 MiB；超限的一行会被拒绝，进程继续服务下一条。`ping` 在工具调用进行中也会返回 - **HTTP 会话**：空闲 TTL 3600 秒、每进程最多 100 个并发会话，容量满返回 503 @@ -274,4 +264,4 @@ CLI server 特有的问题（`abx` 不在 IDE 的 `PATH`、`abx mcp status`） ## 相关：abx CLI -Node.js `abx` CLI 提供自己的 MCP server 及相关命令，记录在 CLI 仓库：[MCP 集成（CLI）](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/guide/mcp-integration.md)（`abx mcp install|start|stop|status|deploy`、IDE 安装目标、后台 HTTP 模式、pid 与日志文件）以及 CLI 的 [MCP Server 设计](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/mcp-server.md)。 +Node.js `abx` CLI 提供自己的 MCP server 及相关命令，记录在 CLI 仓库：[MCP 集成（CLI）](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/guide/mcp-integration.md)（`abx mcp install|start|stop|status`、IDE 安装目标、后台 HTTP 模式、pid 与日志文件）以及 CLI 的 [MCP Server 设计](https://github.com/alibaba-agent-sandbox/agent-sandbox/blob/main/docs/zh/design/mcp-server.md)。 diff --git a/examples/README.md b/examples/README.md index 796772ee..45455424 100644 --- a/examples/README.md +++ b/examples/README.md @@ -61,7 +61,7 @@ examples/ tests. Official & community templates — content, index (`awesome-templates.yaml`), releases and CI — live in the single-source-of-truth repository [`alibaba-agent-sandbox/awesome-templates`](https://github.com/alibaba-agent-sandbox/awesome-templates); -discover and install them with `abx template search` / `abx template launch --yes`. +discover and install them with `abx template list` / `abx deploy --name --yes`. ## Server SDK examples diff --git a/examples/quickstart/README.md b/examples/quickstart/README.md index 6ada466f..f3aecadb 100644 --- a/examples/quickstart/README.md +++ b/examples/quickstart/README.md @@ -1,5 +1,7 @@ # Quickstart Demos +> Historical run output below retains the command names used by that run. For current setup and deployment use [cloud examples](../../docs/en/guide/cloud-examples.md) and [build and deploy](../../docs/en/guide/build-and-deploy.md). + **Client SDK.** These scripts run on your machine. They create a sandbox and use it. The service inside the image is the Server SDK; it is not what these files start. Quickstart demos showing core **Agent Sandbox** SDK capabilities — sandbox lifecycle, file operations, web services, data analysis, and declarative execution. diff --git a/examples/templates/README.md b/examples/templates/README.md index eb87970f..5c0c3c57 100644 --- a/examples/templates/README.md +++ b/examples/templates/README.md @@ -19,7 +19,7 @@ examples/templates/ ``` `python-hello` 是一个最小端到端样例，用于让 `client-sdk/tests/test_templates/` 在**无网络** -条件下驱动真实安装管线（`abx install` 的本地 / GitHub 两种来源、YAML 加载、 +条件下驱动源码获取与配置管线（本地 / GitHub 两种来源、YAML 加载、 缓存布局、容器内命令服务器 E2E）。它与真源仓库中的同名模板保持同步， 但**不从本仓库发布**。 @@ -30,9 +30,9 @@ examples/templates/ （以下 `abx` 命令由独立 `cli` 仓库中的 `abx` CLI 提供。） ```bash -abx template search python # 浏览远程目录（名称 / 标签 / 描述） -abx template install node-web # 裸名 → 通过索引解析 -abx template install alibaba-agent-sandbox/awesome-templates//qwen-code@v1.0.0 # 直接引用 + 版本锁定 +abx template list python # 浏览远程目录（名称 / 标签 / 描述） +abx template init ./node-web --from node-web # 裸名 → 通过索引解析 +abx template init ./qwen-code --from alibaba-agent-sandbox/awesome-templates//qwen-code@ # 直接引用 + 版本锁定 ``` 索引默认地址（可用 `ABX_TEMPLATE_INDEX_URL` / `--index-url` 覆盖）： @@ -49,7 +49,7 @@ https://raw.githubusercontent.com/alibaba-agent-sandbox/awesome-templates/main/a | 网络失败 / GitHub 限流（403/429） | 回退到已缓存副本并给出 warning；无缓存时报 `NetworkError` 并附补救建议 | | `--refresh` | 强制重新拉取（带 `If-None-Match` 条件请求） | | `schema_version` 高于本客户端 | 拒绝解析并提示升级 `agent-sandbox` | -| 索引条目声明 `ref` | `abx template install ` 安装该固定版本 | +| 索引条目声明 `ref` | `abx template init ./project --from ` 获取该固定版本 | | 直接引用 `owner/repo//subdir@ref` | 完全绕过索引（网络失败时的兜底路径） | ## 校验 diff --git a/examples/templates/python-hello/README.md b/examples/templates/python-hello/README.md index 8f53f89f..ec5f9c29 100644 --- a/examples/templates/python-hello/README.md +++ b/examples/templates/python-hello/README.md @@ -1,61 +1,22 @@ -# Python Hello 模板 +# Python Hello 离线夹具 -**Server SDK。** `commands.py` 在沙箱里面启动。`call_api.py` 是 Client SDK：在外面调用已经起来的服务。 +本目录为 Python SDK 的离线测试夹具。`commands.py` 在服务端注册命令，`call_api.py` 从客户端访问已运行的服务。真实模板的镜像、配置和发布说明由 [awesome-templates/python-hello](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/tree/main/python-hello) 维护。 -> **Fixture**：本目录是主仓库的**离线测试夹具**（`client-sdk/tests/test_templates/` 使用）， -> 不是发布真源。模板内容、索引与发布以 -> [`alibaba-agent-sandbox/awesome-templates`](https://github.com/alibaba-agent-sandbox/awesome-templates/tree/main/python-hello) -> 为准。 +## 使用真实模板 -基础 Python 开发环境模板。 - -## 安装 - -> 以下 `abx` 命令由独立 `cli` 仓库中的 `abx` CLI 提供（[CLI binary installation](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/blob/main/docs/en/guide/binary-installation.md)）。 - -```bash -abx install ./examples/templates/python-hello --registry-type local -``` - -## 使用 +安装并配置[当前 CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox#installation) 后： ```bash -abx create --template python-hello +abx deploy python-hello --name hello +abx sandbox command run hello hello --arg name=Alice +abx sandbox command run hello run_script --arg 'code=print(1+1)' +abx sandbox upload hello ./local_file.txt /home/user/app/remote.txt +abx sandbox download hello /home/user/app/remote.txt ./local_file.txt +abx delete hello --yes ``` -### 命名命令（端到端） - -容器启动后会自动运行 `commands.py`，监听端口 9000，提供以下命名命令： - -```bash -# 打招呼 -abx run hello --name Alice -# → Hello, Alice! - -# 执行 Python 代码 -abx run run_script --code "print(1+1)" -# → 2 -``` - -SDK 侧等价写法： - -```python -from agent_sandbox import ProviderSandbox as Sandbox - -sandbox = Sandbox.create_sync(template="python-hello") -print(sandbox.run_sync("hello", name="Alice")) # Hello, Alice! -``` - -### 上传 / 下载 - -```bash -abx upload ./local_file.txt /app/remote.txt -abx download /app/remote.txt ./local_file.txt -``` +部署会生成并在本机保存缺省应用令牌。外部 Python 或 HTTP 调用者需要使用对应令牌及 Provider 返回的访问地址与认证头；见[模板使用指南](../../../docs/zh/guide/template-workflows.md)。安装 SDK 或本地注册函数不会部署该函数。 -## 环境 +## 验证夹具 -- 基础镜像: Ubuntu 22.04 -- Python 3 + pip -- 容器内运行时: [配套源码安装指南](../../../docs/zh/guide/install-python.md)（提供 `agent_sandbox.server`） -- 工作目录: /app +运行 `cd client-sdk && python -m pytest tests/test_templates/ -q`。该检查用于本地行为，不创建云资源。模板内容变更应提交到模板源仓库。 From 34a2174ac57b486ade7ba0cc87c1ba59dc737fcb Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:09:47 +0000 Subject: [PATCH 2/5] fix: align template examples and controllers with named commands --- .../evidence/verify/2026-11-12-ecosystem-guidance-sync.md | 6 ++++++ docs/en/design/template-system.md | 2 +- docs/en/guide/conditional-acceptance.md | 4 ++-- docs/zh/design/template-system.md | 2 +- docs/zh/guide/conditional-acceptance.md | 4 ++-- examples/README.md | 2 +- examples/README.zh-CN.md | 2 +- 7 files changed, 14 insertions(+), 8 deletions(-) diff --git a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md index 14baf9a4..74f777bc 100644 --- a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md +++ b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md @@ -29,3 +29,9 @@ The secret hook initially rejected an environment-variable reference in an MCP example as a generic quoted secret assignment. The example now uses explicit YOUR_* placeholders. No secret value was present and the hook was not changed or bypassed. + +A second scan removed global-option-prefixed template launch examples from +both example indexes and the current template-system descriptions. Conditional +acceptance uses the supported `--opt region=...` Provider override. Historical +SDK quickstart run output remains explicitly labeled as such. No SDK method or +configuration resolver was changed. diff --git a/docs/en/design/template-system.md b/docs/en/design/template-system.md index 9853b6e8..5c4a4028 100644 --- a/docs/en/design/template-system.md +++ b/docs/en/design/template-system.md @@ -14,7 +14,7 @@ not acquire Docker/source-build responsibilities. ## Launch and use -Use `abx --provider PROVIDER template launch TEMPLATE_REF` or Python +Use `abx --provider PROVIDER deploy TEMPLATE_REF` or Python `launch_template(manifest, provider=..., reference=...)`. The launcher checks only operations needed to create, start, inspect readiness and clean up. Missing interpreter operations never prevent an unrelated application from starting. Actual operations diff --git a/docs/en/guide/conditional-acceptance.md b/docs/en/guide/conditional-acceptance.md index 7c013508..27b9ba78 100644 --- a/docs/en/guide/conditional-acceptance.md +++ b/docs/en/guide/conditional-acceptance.md @@ -70,8 +70,8 @@ cat > template-create.json <<'JSON' "envd_inject": false } JSON -abx --provider alicloud-express --region "$REGION" provider run template.create --input-file template-create.json --yes -abx --provider alicloud-express --region "$REGION" provider run template.get --input-file template-get.json +abx --provider alicloud-express --opt "region=$REGION" provider run template.create --input-file template-create.json --yes +abx --provider alicloud-express --opt "region=$REGION" provider run template.get --input-file template-get.json ``` Replace the unique name, Team and image region before running. Put the returned `template_id` and the same `team_id` in `template-get.json`; poll until the build is ready. Submission is asynchronous. The create operation rejects existing names. These commands follow the current source CLI; inspect installed help when using an older release. diff --git a/docs/zh/design/template-system.md b/docs/zh/design/template-system.md index 3153dbfa..82cce73e 100644 --- a/docs/zh/design/template-system.md +++ b/docs/zh/design/template-system.md @@ -11,7 +11,7 @@ ## 启动与使用 -CLI 使用 `abx --provider PROVIDER template launch TEMPLATE_REF`；Python 使用 +CLI 使用 `abx --provider PROVIDER deploy TEMPLATE_REF`；Python 使用 `launch_template(manifest, provider=..., reference=...)`。启动前只检查创建、启动、 就绪和清理实际需要的操作。缺少解释器不阻止无关应用启动。执行具体操作时， Provider 和服务端策略仍负责实际能力与权限检查。 diff --git a/docs/zh/guide/conditional-acceptance.md b/docs/zh/guide/conditional-acceptance.md index a3fc4f27..7fa31c32 100644 --- a/docs/zh/guide/conditional-acceptance.md +++ b/docs/zh/guide/conditional-acceptance.md @@ -70,8 +70,8 @@ cat > template-create.json <<'JSON' "envd_inject": false } JSON -abx --provider alicloud-express --region "$REGION" provider run template.create --input-file template-create.json --yes -abx --provider alicloud-express --region "$REGION" provider run template.get --input-file template-get.json +abx --provider alicloud-express --opt "region=$REGION" provider run template.create --input-file template-create.json --yes +abx --provider alicloud-express --opt "region=$REGION" provider run template.get --input-file template-get.json ``` 执行前替换唯一名称、Team 和镜像地域。将返回的 `template_id` 与相同的 `team_id` 写入 `template-get.json`，轮询直到构建就绪。提交是异步操作，注册时拒绝已有名称。这些命令对应当前源码 CLI；使用较早发行版时先查看已安装的帮助。 diff --git a/examples/README.md b/examples/README.md index 45455424..934d7698 100644 --- a/examples/README.md +++ b/examples/README.md @@ -157,7 +157,7 @@ requires the CLI's documented Docker/registry configuration. ```bash export ABX_SERVER_TOKEN='replace_me' -abx --provider alicloud-express template launch 'alibaba-agent-sandbox/awesome-templates//python-hello' +abx --provider alicloud-express deploy 'alibaba-agent-sandbox/awesome-templates//python-hello' ``` Use the returned ID as `SANDBOX_ID` and the same application token: diff --git a/examples/README.zh-CN.md b/examples/README.zh-CN.md index 97203451..17b1466f 100644 --- a/examples/README.zh-CN.md +++ b/examples/README.zh-CN.md @@ -149,7 +149,7 @@ python-hello。源码准备需要 CLI 文档中的 Docker 和镜像仓库配置 ```bash export ABX_SERVER_TOKEN='replace_me' -abx --provider alicloud-express template launch 'alibaba-agent-sandbox/awesome-templates//python-hello' +abx --provider alicloud-express deploy 'alibaba-agent-sandbox/awesome-templates//python-hello' ``` 将返回的标识写入 `SANDBOX_ID`，使用相同的应用令牌： From 358945cbd0e73935866702c3e6222ca02c03c9e3 Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:15:19 +0000 Subject: [PATCH 3/5] docs: finish provider and versioned guidance audit --- .agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md | 2 ++ docs/en/guide/permissions.md | 2 +- docs/zh/guide/permissions.md | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md index 74f777bc..a4d63b9f 100644 --- a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md +++ b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md @@ -35,3 +35,5 @@ both example indexes and the current template-system descriptions. Conditional acceptance uses the supported `--opt region=...` Provider override. Historical SDK quickstart run output remains explicitly labeled as such. No SDK method or configuration resolver was changed. + +Final permission-guide review removed the obsolete claim that CI output authorizes key preparation. Existing explicit SDK confirmation remains required; no key was created or renewed during this task. diff --git a/docs/en/guide/permissions.md b/docs/en/guide/permissions.md index 2bb78ca5..c0c528a3 100644 --- a/docs/en/guide/permissions.md +++ b/docs/en/guide/permissions.md @@ -20,4 +20,4 @@ finally: Async code uses `await prepare_api_key(confirm=True)` and may then use `AsyncSandbox` or `ProviderSandbox`. Default `confirm=False` rejects before engine/cloud I/O. Preparation returns metadata, never plaintext. Reuse checks cloud status. Near-expiry keys need fresh explicit preparation; already constructed clients do not renew in the background. Disabling or deleting a key is respected. The engine owns expiry and shared private storage, with no duplicated cloud SDK in Python. -The optional `team_id=` selector must match subsequent engine selection. For persistent selection use `abx config set team_id ` so CLI and SDK share the same context; otherwise both use the API's default Team. In CI, `abx --ci sandbox list --format json` explicitly authorizes preparation before starting the SDK application. See the owner guide for recovery after uncertain writes and exact cleanup permissions. +The optional `team_id=` selector must match subsequent engine selection. For persistent selection use `abx config set team_id ` so CLI and SDK share the same context; otherwise both use the API's default Team. In CI, configure an existing Sandbox API key or perform the explicit SDK preparation shown above before starting the application. `--ci` selects machine output and does not authorize credential creation or renewal. See the owner guide for recovery after uncertain writes and exact cleanup permissions. diff --git a/docs/zh/guide/permissions.md b/docs/zh/guide/permissions.md index 26a6cd16..e9b8d5ca 100644 --- a/docs/zh/guide/permissions.md +++ b/docs/zh/guide/permissions.md @@ -20,4 +20,4 @@ finally: 异步使用 `await prepare_api_key(confirm=True)`，然后可用 `AsyncSandbox` 或 `ProviderSandbox`。默认 `confirm=False` 在引擎/云端 I/O 前拒绝。准备只返回元数据，不返回明文。复用时检查云端状态，临近到期需要重新显式准备；已构造客户端不会后台续期。禁用和删除不会被绕过。引擎负责有效期和共享私有存储，Python 不重复实现云 SDK。 -可选 `team_id=` 必须与后续引擎选择一致。建议用 `abx config set team_id ` 持久化，使 CLI/SDK 使用同一上下文；省略时均使用接口默认 Team。CI 可先运行 `abx --ci sandbox list --format json` 明确授权准备，再启动 SDK 应用。未知写入结果的恢复步骤和精确清理权限见上述完整指南。 +可选 `team_id=` 必须与后续引擎选择一致。建议用 `abx config set team_id ` 持久化，使 CLI/SDK 使用同一上下文；省略时均使用接口默认 Team。CI 应配置已有的沙箱 API Key，或先执行上文显式确认的 SDK 准备步骤，再启动应用。`--ci` 只控制机器输出，不授予创建或续期凭据的权限。未知写入结果的恢复步骤和精确清理权限见上述完整指南。 From 47c43b43e3921fe3368d5e22a7515064430ed3b0 Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:35:56 +0000 Subject: [PATCH 4/5] docs: record verified authenticated delivery path --- .../verify/2026-11-12-ecosystem-guidance-sync.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md index a4d63b9f..71f01827 100644 --- a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md +++ b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md @@ -37,3 +37,12 @@ SDK quickstart run output remains explicitly labeled as such. No SDK method or configuration resolver was changed. Final permission-guide review removed the obsolete claim that CI output authorizes key preparation. Existing explicit SDK confirmation remains required; no key was created or renewed during this task. + +## Authentication and delivery follow-up + +The initial API Bearer request returned HTTP401, but the credential was not +invalid. Git push/fetch and the API's Basic authentication succeeded with the +same existing credential; no credential was changed or created. Public +producer source branches can now be pushed. Private Registry/Website main was +fetched successfully, and the prior coordinating PRs were confirmed merged. +This supersedes the initial delivery-authentication limitation above. From b7a1e75a6c0d5b04842c668c0e3d6a35471ac291 Mon Sep 17 00:00:00 2001 From: anycodes <21079031+anycodes@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:42:13 +0000 Subject: [PATCH 5/5] test: align fixture guidance guards with current CLI --- .../verify/2026-11-12-ecosystem-guidance-sync.md | 11 +++++++++++ .../tests/test_templates/test_template_catalog.py | 6 +++--- examples/templates/python-hello/README.md | 2 +- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md index 71f01827..ddf0685c 100644 --- a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md +++ b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md @@ -46,3 +46,14 @@ same existing credential; no credential was changed or created. Public producer source branches can now be pushed. Private Registry/Website main was fetched successfully, and the prior coordinating PRs were confirmed merged. This supersedes the initial delivery-authentication limitation above. + +## Remote fixture-boundary regression + +The first remote client matrix found two documentation guard failures: the +existing source-flow check still required retired search/install commands, +and the rewritten Chinese fixture title omitted its explicit English fixture +marker. Updated the existing assertions to list/init and restored the bilingual +marker, preserving the fixture boundary rather than weakening it. The failures +were reproduced locally (2 failed, 35 passed, one skipped) and in the full +remote suite (2 failed, 2,450 passed on Python3.12). The corrected focused suite +passed (37 passed, one skipped); full remote matrix results remain separate. diff --git a/client-sdk/tests/test_templates/test_template_catalog.py b/client-sdk/tests/test_templates/test_template_catalog.py index 0c1d7ea5..29674174 100644 --- a/client-sdk/tests/test_templates/test_template_catalog.py +++ b/client-sdk/tests/test_templates/test_template_catalog.py @@ -218,10 +218,10 @@ def test_index_readme_links_the_source_of_truth(self, catalog_readme: Path) -> N f"({SOURCE_OF_TRUTH_URL})" ) - def test_index_readme_documents_remote_install_flow(self, catalog_readme: Path) -> None: + def test_index_readme_documents_remote_source_flow(self, catalog_readme: Path) -> None: readme = catalog_readme.read_text(encoding="utf-8") - assert "abx template search" in readme - assert "abx template install" in readme + assert "abx template list" in readme + assert "abx template init" in readme assert "ABX_TEMPLATE_INDEX_URL" in readme, ( "README must document the index override for private mirrors" ) diff --git a/examples/templates/python-hello/README.md b/examples/templates/python-hello/README.md index ec5f9c29..c971b01a 100644 --- a/examples/templates/python-hello/README.md +++ b/examples/templates/python-hello/README.md @@ -1,4 +1,4 @@ -# Python Hello 离线夹具 +# Python Hello 离线夹具（Offline fixture） 本目录为 Python SDK 的离线测试夹具。`commands.py` 在服务端注册命令，`call_api.py` 从客户端访问已运行的服务。真实模板的镜像、配置和发布说明由 [awesome-templates/python-hello](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/tree/main/python-hello) 维护。