diff --git a/.agents/README.md b/.agents/README.md index 3604a6e..881cde0 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -21,6 +21,8 @@ records 14 actual cloud examples, 29 independent typed-not-found checks and the separate 10-check local runner with real timeout controls. Earlier version receipts and variable browser cold-install observations remain unchanged. +[Template startup ownership documentation](notes/proposed/process/2026-10-25-template-startup-ownership.md) clarifies preparation versus connection; [verification](evidence/verify/2026-10-25-template-startup-ownership.md) records the bounded public-a6 startup/auth observation separately from full catalog acceptance. + ## Previous public a4 delivery — 2026-10-25 [Public-a4 example acceptance](evidence/verify/2026-10-25-public-a4-examples.md) diff --git a/.agents/evidence/verify/2026-10-25-template-startup-ownership.md b/.agents/evidence/verify/2026-10-25-template-startup-ownership.md new file mode 100644 index 0000000..b88a68e --- /dev/null +++ b/.agents/evidence/verify/2026-10-25-template-startup-ownership.md @@ -0,0 +1,24 @@ +# Verification: template startup ownership documentation + +- Date: 2026-10-25 +- Result: PARTIAL — existing public-package observation passed; local documentation checks passed; exact-head required CI and merge are pending. +- Base: ec3bcf1eb788acb42fea32dec06537ef915e9ba2. +- Change: bilingual template consumption/authoring/design overview prose, SDK Skill specification number and owner records only. Client/server remain public 0.4.0a6; no source implementation or package version change. + +## Real public-package observation + +A bounded owner experiment used actual official client/server 0.4.0a6 and public CLI 0.5.5. The advanced preparation stage contained only template.yaml with native startup/readiness fields removed; the original application manifest was passed unchanged to Python. This is one explicitly inspected preparation path, not a generic promise about empty CLI flags or all providers. + +Before Python startup, actual port 9000 was closed and no application server process existed. After startup, the port was open, exactly one server existed, and its token was present and matched. Actual HTTP application calls returned 200 with result 8 for the correct token and 401 for both missing and incorrect tokens. Bearer and the existing same-value application fallback header were tested together. Neither credentials nor resource IDs are recorded here. + +The exact one owned sandbox was independently absent via typed lookup after cleanup; the exact one owned prepared template was independently absent with E2001 and its alias absent. No owned resources remained. This observation does not certify other preparation paths or all providers. No candidate runtime was used or needed. + +## Owner checks + +`bash scripts/check-repo-health.sh`: 106 PASS, one existing missing release-guide recommendation WARN, zero FAIL. `make hygiene` and `git diff --check`: PASS. No runtime/tests changed; no additional cloud resources were created for prose checks. Full exact-head remote checks remain pending. Earlier full local checks from a separate investigation are not a pass for this head: the server suite observed one WebSocket status mismatch (879 pass, 1 fail); the cause was not established. No server behavior or gate is changed here. Remote required matrix results must be read for the exact new head. + +## Not verified + +This is prose only. No new whole-catalog, provider matrix, model or performance claim is made. Previous package and example receipts remain unchanged. + +Issue: https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/133 diff --git a/.agents/notes/proposed/process/2026-10-25-template-startup-ownership.md b/.agents/notes/proposed/process/2026-10-25-template-startup-ownership.md new file mode 100644 index 0000000..7f30b8c --- /dev/null +++ b/.agents/notes/proposed/process/2026-10-25-template-startup-ownership.md @@ -0,0 +1,38 @@ +# Decision: Clarify template startup ownership + +Status: proposed + +## Problem + +The prepared-reference guide does not explain that ordinary native deployment can retain its own startup command. Combining that reference with a manifest startup can run the same service twice. The SDK Skill also says specification 4 above a specification 5 manifest. + +## Decision + +Recommend unified CLI source launch followed by SDK connection. Describe Python prepared-reference launch as an advanced path that creates a sandbox and owns the manifest startup; its native entrypoint must not duplicate that service. Correct the Skill prose to specification 5. + +## API Design + +N/A — this decision does not involve API changes. No new preparation mode, selector, environment alias or package version. + +## Alternatives considered + +A generic empty-startup flag recipe would hide profile-dependent preparation and does not establish that a service is idle. A runtime modification is unnecessary: the controlled official a6 experiment already passed the documented startup and authentication behavior. + +## Dependencies + +- https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/133 + +- https://github.com/Alibaba-Agent-Sandbox/python-sdk/releases/tag/v0.4.0a6 +- https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/releases/tag/v0.5.5 + +## Test Strategy + +Preserve the existing bounded real public-package startup/auth/owned-cleanup result, inspect current CLI/SDK startup semantics, and run owner documentation, hygiene and exact-head required CI checks. Do not relabel other preparation paths or the catalog as tested. + +## Acceptance criteria + +Both languages distinguish CLI connection from Python-owned startup without inventing another user-facing state. Skill prose matches its manifest. No Python implementation, test, dependency or version changes; required checks, review and normal merge complete. + +## Evidence + +- [Verification](../../../evidence/verify/2026-10-25-template-startup-ownership.md) diff --git a/CHANGELOG.md b/CHANGELOG.md index 78f3c82..ca2fd9b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ### Changed +- Clarify CLI-started application connection versus Python-owned prepared-reference startup in both template guides; correct the SDK Skill's specification number to 5. No runtime, API or package version change. / 双语模板指南区分 CLI 启动后连接与 Python 根据已准备引用启动，避免重复启动同一个服务；SDK 技能的规范编号更正为 5，不改运行行为、接口或版本。 + - Select verified public client/server a6 in maintained bilingual installs, Skills and runtime fixtures. Preserve immutable publication hashes, exhaustive help checks and real current-design cleanup separately from earlier a4/a5 receipts. No runtime/API change or new package publication. / 维护中的双语安装、技能与运行夹具统一使用已验证公开 a6；另存不可变产物摘要、完整帮助检查与真实设计示例清理结果，不改旧 a4/a5 证据，不改运行接口或另发包。 ### Fixed diff --git a/agent-sandbox-sdk/SKILL.md b/agent-sandbox-sdk/SKILL.md index 7a86de5..5971cfa 100644 --- a/agent-sandbox-sdk/SKILL.md +++ b/agent-sandbox-sdk/SKILL.md @@ -128,7 +128,7 @@ 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 [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: +Use strict specification 5. `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 diff --git a/docs/en/DESIGN.md b/docs/en/DESIGN.md index e1a10cb..358ea09 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. Templates are built and deployed with `abx template build|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 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)). 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)). @@ -127,7 +127,7 @@ Chinese copies of these pages live under `docs/zh/`. `repository-layout.md` is E | 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 build/push/deploy | **In the CLI** | `abx template build` and `abx template deploy`; the SDK does not build templates | +| 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` | | 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/guide/authoring-templates.md b/docs/en/guide/authoring-templates.md index 3819744..f0a8c3c 100644 --- a/docs/en/guide/authoring-templates.md +++ b/docs/en/guide/authoring-templates.md @@ -148,7 +148,7 @@ the sandbox creator owns its final deletion. ## Publishing and Deploying Templates -The Python SDK is the runtime client and does not build or deploy templates. Build, push and register a template with the CLI: `abx template build` and `abx template deploy` (or `abx deploy`). See [Build & Deploy](build-and-deploy.md). +The Python SDK is the runtime client and does not build source templates. Normally use `abx --provider PROVIDER template launch SOURCE --yes`, then connect Python to the returned sandbox. Advanced image preparation uses `abx template build` and `abx template deploy`; before passing a prepared reference to `launch_template`, ensure its native startup does not also start the same service. See [startup ownership](template-workflows.md) and [Build & Deploy](build-and-deploy.md). To publish a template to GitHub, install one locally or from a registry, adopt an existing project (`abx template scaffold --adopt`), or build and register one from the command line (`abx deploy`, `abx template deploy|create`), use the `abx` CLI; see [Related: the abx CLI](#related-the-abx-cli). diff --git a/docs/en/guide/template-workflows.md b/docs/en/guide/template-workflows.md index a15818e..0b43660 100644 --- a/docs/en/guide/template-workflows.md +++ b/docs/en/guide/template-workflows.md @@ -1,6 +1,6 @@ # Launch and use a template -Use the CLI to prepare a source template, then connect with Python. If the platform already provides a template ID, Python can create it directly. +Use `abx --provider PROVIDER template launch SOURCE --yes` to prepare and start a source template, then connect with Python using the returned sandbox ID and the same provider. If the platform already provides a template ID, Python can create it directly. ## Python application consumption @@ -21,7 +21,9 @@ finally: The client also sends the explicit application token in the server's existing `X-Access-Token` header when that header is unused. This keeps authentication working through proxies that strip `Authorization`, including OpenSandbox 1.1.1. Existing gateway headers, including defaults on an injected HTTP client, are never replaced. Bearer authentication remains available for services that require it. -To start the complete template from a prepared provider reference: +For advanced preparation, `launch_template` creates a new sandbox from a prepared provider reference and runs the manifest's `start_cmd`. The reference must not also start the same service through its native startup command or image entrypoint. An ordinary `abx template deploy` can retain native startup behavior; its returned reference is not automatically idle. If the CLI has already started the application, connect to its sandbox as above. + +To let Python own startup and cleanup after checking that preparation boundary: ```python from agent_sandbox.api import launch_template @@ -43,8 +45,8 @@ only when there is exactly one SandboxServer. With several, call `session.servers["service-name"].commands.run(...)` to choose the invocation target. Choosing a client never changes which template services were started. -Python does not build sources. Prepare them with the CLI and pass the resulting -provider reference, or connect to the sandbox returned by the CLI. A manifest may +Python does not build sources. Source preparation belongs to the CLI; choose one +startup owner as described above. A manifest may also declare a fixed digest-pinned `image`, or `provider` plus `template_id` for a platform-managed template. References are interpreted by that Provider; native IDs need no artificial version. For an existing external HTTP service, use `ServerClient` diff --git a/docs/zh/DESIGN.md b/docs/zh/DESIGN.md index 171220b..41b931b 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 build|deploy` 构建和部署。方法名参考了 E2B，方便迁移，标准公开接口遵循阿里云支持的 E2B 行为契约（见[从 E2B 迁移](guide/migrate-from-e2b.md)）。 +**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)）。 本仓库包含 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)）。 @@ -127,7 +127,7 @@ graph TB | 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-部署) | -| 模板 build/push/deploy | **在 CLI 中** | `abx template build` 与 `abx template deploy`；SDK 不构建模板 | +| 模板启动与镜像准备 | **在 CLI 中** | 使用 `abx template launch` 启动源码，再由 SDK 连接；高级镜像准备使用 `abx template build` 与 `abx template 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/guide/authoring-templates.md b/docs/zh/guide/authoring-templates.md index 15b93ef..17f365b 100644 --- a/docs/zh/guide/authoring-templates.md +++ b/docs/zh/guide/authoring-templates.md @@ -143,7 +143,7 @@ if __name__ == "__main__": ## 发布与部署模板 -Python SDK 是运行时客户端，不构建也不部署模板。构建、推送并注册模板用 CLI：`abx template build` 和 `abx template deploy`（或 `abx deploy`）。见[构建与部署](build-and-deploy.md)。 +Python SDK 是运行时客户端，不构建源码模板。通常使用 `abx --provider PROVIDER template launch SOURCE --yes`，再用 Python 连接返回的沙箱。高级镜像准备使用 `abx template build` 和 `abx template deploy`；将准备好的引用传给 `launch_template` 前，确认原生启动路径不会同时启动同一个服务。见[启动方说明](template-workflows.md)和[构建与部署](build-and-deploy.md)。 将模板发布到 GitHub、从本地或 registry 安装模板、适配已有项目（`abx template scaffold --adopt`），或通过命令行构建并注册模板（`abx deploy`、`abx template deploy|create`），请使用 `abx` CLI；见[相关：abx CLI](#相关abx-cli)。 diff --git a/docs/zh/guide/template-workflows.md b/docs/zh/guide/template-workflows.md index 4f7512b..2c2d00b 100644 --- a/docs/zh/guide/template-workflows.md +++ b/docs/zh/guide/template-workflows.md @@ -1,6 +1,6 @@ # 启动和使用模板 -源码模板先用 CLI 准备并启动，再用 Python 连接。平台已经提供模板 ID 时，可以直接用 Python 创建。 +源码模板使用 `abx --provider PROVIDER template launch SOURCE --yes` 准备并启动，再用 Python 通过返回的沙箱 ID 和同一个 Provider 连接。平台已经提供模板 ID 时，可以直接用 Python 创建。 ## Python 应用调用 @@ -21,7 +21,9 @@ finally: 如果 `X-Access-Token` 请求头未被占用，客户端还会通过服务端已有的这个请求头发送同一个显式应用令牌，使认证能通过 OpenSandbox 1.1.1 等会过滤 `Authorization` 的代理。已有网关请求头（包括注入 HTTP 客户端的默认请求头）不会被覆盖；需要 Bearer 的服务仍可使用原认证方式。 -通过已准备好的 Provider 引用启动完整模板： +高级准备场景中，`launch_template` 根据已准备好的 Provider 引用创建新沙箱，并执行清单的 `start_cmd`。该引用的原生启动命令或镜像入口不能同时启动同一个服务。普通 `abx template deploy` 可能保留原生启动行为，返回的引用不自动代表应用尚未启动。如果 CLI 已启动应用，按上文连接它返回的沙箱即可。 + +确认准备阶段没有重复启动后，让 Python 负责启动和清理： ```python from agent_sandbox.api import launch_template @@ -41,7 +43,7 @@ async with await launch_template( 多个时使用 `session.servers["服务名"].commands.run(...)` 选择调用目标。 这不会改变已经整体启动的模板内容。 -Python 不构建源码。先使用 CLI 准备并传入生成的 Provider 引用，或连接 CLI 返回的沙箱。 +Python 不构建源码；源码准备由 CLI 负责，按上文选择一个启动方。 模板也可声明固定摘要的 `image`，或者 `provider` 与 `template_id` 原生模板标识。 引用由 Provider 解释，原生 ID 不需要虚构版本。已有外部 HTTP 服务直接使用 `ServerClient`；应用部署 hook 仍由部署编排器处理。