diff --git a/.agents/evidence/verify/2026-10-24-package-installation-docs.md b/.agents/evidence/verify/2026-10-24-package-installation-docs.md new file mode 100644 index 00000000..5e0288c6 --- /dev/null +++ b/.agents/evidence/verify/2026-10-24-package-installation-docs.md @@ -0,0 +1,27 @@ +# Verification: packaged Python installation guidance + +- Date: 2026-10-24 +- Change: [Issue #101](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/101), based on `8b77f789111a92713de51573cbb7e8ff7411e9c4`. +- Result: PASS for local packaging and document changes; public a5 publication is not included in this result. +- Packages: matching 0.3.1a5 client/server built locally on Python 3.12. + +## What was verified + +The actual wheel METADATA and source-archive README for both distributions contain corrected prerelease installation instructions and no old a2 pin. Client metadata requires exactly `agent-sandbox-server==0.3.1a5`. Apart from the version declarations, application runtime code is unchanged from the real proxy-tested a4 candidate. + +## Commands run and results + +- `python -m pytest client-sdk/tests/test_release_validation.py client-sdk/tests/test_packaging.py -q`: 9 passed in 3.85 seconds. +- `python -m pytest server-sdk/tests/test_packaging.py -q`: 5 passed in 0.74 seconds. +- `make build dist-check`: passed; both wheel/sdist pairs, twine, py.typed and combined clean installation/imports. +- Inspected each wheel's METADATA with `zipfile` and `email`, and each sdist README with `tarfile`: matching a5 versions and dependency, corrected descriptions in all four artifacts. +- `git diff --check` and repository health passed (106 PASS, 1 existing warning, 0 failures). +- Initial [CI 40112322302](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/40112322302) failed hygiene because the new guide creates and activates `.venv`, which matched the broad virtualenv assumption guard. Added narrowly anchored allowlist entries for that exact activation command in the two installation guides; the environment is explicitly created immediately above. The guard itself and credential rules are unchanged. Corrected `make hygiene` passed; current-head full CI and links remain required before merge. + +## Preserved publication history + +[a4 publication run 40111654824](https://github.com/Alibaba-Agent-Sandbox/python-sdk/actions/runs/40111654824) was intentionally cancelled during validation after the stale packaged instructions were found. Its Build & Publish job ended cancelled with an empty steps list: no upload step executed. Both exact a4 PyPI JSON endpoints returned 404 at readback. The immutable `v0.3.1a4` tag remains at `8b77f789111a92713de51573cbb7e8ff7411e9c4`; release metadata clearly says it was not published to PyPI. Cancellation is not a test pass. + +## Real runtime evidence and limits + +[OpenSandbox T4 40110372103](https://github.com/Alibaba-Agent-Sandbox/awesome-providers/actions/runs/40110372103) verified the unchanged runtime through default/direct, portable/direct and default/proxy application paths with independent cleanup. This documentation/package correction creates no cloud resources and does not repeat that cloud test. Public a5 readback and the complete template matrix remain separate follow-up gates; no all-template or real-model claim is made here. diff --git a/.agents/notes/proposed/process/2026-10-24-package-installation-docs.md b/.agents/notes/proposed/process/2026-10-24-package-installation-docs.md new file mode 100644 index 00000000..f496a0ac --- /dev/null +++ b/.agents/notes/proposed/process/2026-10-24-package-installation-docs.md @@ -0,0 +1,43 @@ +# Decision: Keep packaged installation guidance accurate + +Status: proposed + +## Problem + +The package READMEs and installation guide still instructed users to install 0.3.1a2 and described publication as pending. A new wheel would carry these obsolete instructions into its PyPI description even if the website were corrected. + +## Decision + +Use an explicit prerelease opt-in command in package and root READMEs, and a fixed current version in the bilingual installation guide. Start the guide with public package installation; put development checkout instructions later and move publication mechanics into CONTRIBUTING. Keep the exact client/server dependency. + +Stop the a4 publication before upload and preserve its tag. Package the corrected descriptions as matching 0.3.1a5 distributions; do not replace existing version contents. No application runtime behavior changes from a4. + +## API Design + +No public API change. The local client and server distributions remain versioned in lockstep. + +## Alternatives considered + +- Correct only the website: leaves obsolete commands in PyPI descriptions. +- Move the a4 tag or upload modified artifacts under it: breaks the tag-to-artifact relationship. +- Keep publication and verification state prose in the installation path: makes ordinary installation needlessly confusing. + +## Dependencies + +Existing package READMEs, release validator, build pipeline and exact same-version dependency. + +## Test Strategy + +Run package/release regressions and build/dist-check. Inspect the wheel metadata and source archive README for both distributions. Require full current-head CI, then verify public artifact digests, a fresh exact-version install, imports and pip check. Existing real proxy evidence applies to unchanged runtime code; final public-package template acceptance remains separately recorded. + +## Acceptance criteria + +- Both built descriptions give accurate installation commands. +- Bilingual guides use the public pair with no stale candidate state prose. +- a4 tag remains unchanged and no a4 upload occurred. +- a5 public distribution readback and fresh installation succeed. + +## Evidence + +- [Issue #101](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/101) +- [Local packaging and stopped upload](../../../evidence/verify/2026-10-24-package-installation-docs.md) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index b08e724e..513c408f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -241,3 +241,9 @@ requirements still apply. 须确认最新提交的运行、类型、测试和构建任务实际完成；仅 Markdown 检查通过 不能证明产品验证完成。直接推送仍仅在 `main` 触发；真实组件证据和其余完成 标准继续适用。 + +## Publishing the Python pair + +Publish both distributions from a matching `v` tag. The publication workflow runs the full reusable CI suite at that tag, builds and preserves one wheel/sdist pair per distribution, and verifies a combined clean installation. Manual runs default to dry-run. Before upload, existing PyPI files must match the candidate SHA-256; `skip-existing` is not sufficient verification. Upload server before client, then verify public digests and a fresh exact-version client installation with its automatic server dependency and `pip check`. Inspect the README embedded in both packages: it must not send users to an obsolete version. Preserve tags and artifacts; a content change uses a new version. + +两个发行包从匹配的 `v` 标签发布，先执行完整 CI，再构建、保存并检查配套产物。手动运行默认 dry-run。上传前核对 PyPI 已有文件的 SHA-256，不能只依赖 `skip-existing`。先上传服务端，再上传客户端；随后检查公开摘要、新环境精确版本安装、自动服务端依赖和 `pip check`。检查双包内的 README，避免把用户导向旧版本。保留既有标签与产物，内容变更使用新版本号。 diff --git a/CHANGELOG.md b/CHANGELOG.md index c58022a3..13a94e2d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). - Native `ProviderSandbox.commands.run/start/stream(user=...)` now selects the requested envd OS account per request, preserving gateway credentials and concurrent/default identities. Prepare the matching client/server 0.3.1a2 alpha pair; publication is separate. / 原生进程调用按请求选择指定操作系统账号，保留网关凭据以及并发、默认身份；准备配套 0.3.1a2 alpha 双包，发布独立执行。 - Clarify provider-native application clients, published alpha installation, separate gateway/application credentials, and explicit readiness checks after cloud-steps submission in bilingual guides. +## [0.3.1a5] - 2026-10-24 + +### Fixed + +- Correct package README installation commands and simplify bilingual installation guides. Both distributions include the application proxy fix from the a4 source candidate; its PyPI upload was stopped before publication to correct stale package metadata. / 修正随包发布的安装说明，简化中英文安装指南。双包包含 a4 源码候选的应用代理修复；a4 在上传前停止，以修正陈旧的包说明。 + ## [0.3.1a4] - 2026-10-24 ### Fixed diff --git a/README.md b/README.md index 49640d5b..82a7b596 100644 --- a/README.md +++ b/README.md @@ -63,34 +63,16 @@ Provider management operations are available through `agent_sandbox.providers.co ## Installation -The [installation guide](docs/en/guide/install-python.md) provides a tested 0.3.0 Git source pair and explicit opt-in instructions for the 0.3.1a2 alpha once its publication is verified. Both source URLs must use the same commit. +Use Python 3.10 or newer in a virtual environment. The client installs its matching server dependency automatically. See the [installation guide](docs/en/guide/install-python.md) for a pinned version, optional extras and development setup. ```bash -# Client and matching runtime -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" - -# Optional extras (MCP + fast JSON + sessions + declarative) -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[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk" - -# Container-side runtime (install this inside your sandbox image) -python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" -pip install playwright # only if you enable the browser capability group - -# Development (from the repository root; includes test & lint tooling for both packages) -pip install -e ./server-sdk -e "./client-sdk[dev]" +python -m pip install --upgrade --pre agent-sandbox-client +python -m pip check ``` -Do not run `pip install agent-sandbox`. That name on PyPI is an unrelated project. This client is `agent-sandbox-client`. +`--pre` opts into alpha releases. The command-line tool is installed separately: see [the abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox). -`agent-sandbox-client` depends on `agent-sandbox-server` of the same version, so installing the [paired sources](docs/en/guide/install-python.md) also provides `agent_sandbox.server` (needed locally by the `@sandbox` decorator's server proxy). - -The `abx` CLI is no longer part of the Python package (there is no `[cli]` extra and no `abx` -console script); it is distributed from the [`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) repository -(see [Related: the abx CLI](#related-the-abx-cli)). +Do not run `pip install agent-sandbox`; that PyPI name belongs to an unrelated project. ## Quick Start diff --git a/README.zh-CN.md b/README.zh-CN.md index de3be28b..c6824056 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -61,33 +61,16 @@ Node.js 项目，位于 [`agent-sandbox`](https://github.com/alibaba-agent-sandb ## 安装 -[安装指南](docs/zh/guide/install-python.md)提供已验证的0.3.0 Git 配套源码，以及0.3.1a2 alpha 在公开发布验证完成后的显式安装方式。两个源码 URL 必须固定同一提交。 +使用 Python 3.10 或更高版本及虚拟环境。客户端会自动安装同版本的服务端依赖。固定版本、可选依赖及开发安装见[安装指南](docs/zh/guide/install-python.md)。 ```bash -# 仅核心客户端 SDK -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" - -# 完整安装（MCP + 快速 JSON + 会话 + 声明式 + server） -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[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk" - -# 容器侧运行时（安装到你的沙箱镜像内） -python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" -pip install playwright # 仅在启用 browser 能力组时需要 - -# 开发环境（在仓库根目录执行；含两个包的测试与 lint 工具） -pip install -e ./server-sdk -e "./client-sdk[dev]" +python -m pip install --upgrade --pre agent-sandbox-client +python -m pip check ``` -不要执行 `pip install agent-sandbox`。PyPI 上的 `agent-sandbox` 是另一个无关项目。安装本客户端请使用 [配套源码安装指南](docs/zh/guide/install-python.md)。 +`--pre` 表示选择 alpha 预发布版本。命令行工具独立安装，见 [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox)。 -`agent-sandbox-client` 依赖同版本的 `agent-sandbox-server`，因此 [配套源码安装指南](docs/zh/guide/install-python.md) 同样会提供 `agent_sandbox.server`（`@sandbox` 装饰器的 server 代理在本地需要它）。 - -`abx` CLI 不再属于 Python 包（不再有 `[cli]` extra，也没有 `abx` 控制台脚本），由 -[`agent-sandbox`](https://github.com/alibaba-agent-sandbox/agent-sandbox) 仓库分发（见[相关：abx CLI](#相关abx-cli)）。 +不要执行 `pip install agent-sandbox`；该 PyPI 名称属于另一个无关项目。 ## 快速开始 diff --git a/client-sdk/README.md b/client-sdk/README.md index ad30464a..3bbc7354 100644 --- a/client-sdk/README.md +++ b/client-sdk/README.md @@ -2,7 +2,7 @@ Provider extensions use [explicit template workflows](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/template-workflows.md) ([中文](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/zh/guide/template-workflows.md)); application HTTP, stateless execution and context operations are independent. -This package is the opt-in **0.3.1a2 alpha** candidate. Use its exact PyPI version after verified publication; before that, use the [tested paired source recipe](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md). Alpha publication does not establish every provider or template as production-ready. +Install the current alpha with `--pre`; use the [installation guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md) for a pinned version and environment setup. **Client SDK.** The product is Agent Sandbox. The import path is `agent_sandbox`. This package runs on your machine: create a sandbox, use it, and kill it. The HTTP service inside the image is [`agent-sandbox-server`](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/server-sdk/README.md). Guide: [Client SDK](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/client-sdk.md). @@ -19,9 +19,9 @@ The command-line tool (`abx`) is a separate Node.js project that lives in the [` ## Install ```bash -python -m pip install 'agent-sandbox-client==0.3.1a2' +python -m pip install --upgrade --pre agent-sandbox-client # Optional extras: -python -m pip install 'agent-sandbox-client[all]==0.3.1a2' +python -m pip install --upgrade --pre 'agent-sandbox-client[all]' python -m pip check ``` diff --git a/client-sdk/pyproject.toml b/client-sdk/pyproject.toml index 5d8ec3c9..86f6c385 100644 --- a/client-sdk/pyproject.toml +++ b/client-sdk/pyproject.toml @@ -44,7 +44,7 @@ dependencies = [ "tomli>=2.0; python_version < '3.11'", # The client uses the matching local server runtime for its server/declarative helpers. # Keep the required distribution version equal to ``_version.py``. - "agent-sandbox-server==0.3.1a4", + "agent-sandbox-server==0.3.1a5", ] [project.optional-dependencies] diff --git a/client-sdk/src/agent_sandbox/_version.py b/client-sdk/src/agent_sandbox/_version.py index 7d2cb4b3..ea816294 100644 --- a/client-sdk/src/agent_sandbox/_version.py +++ b/client-sdk/src/agent_sandbox/_version.py @@ -1 +1 @@ -__version__ = "0.3.1a4" +__version__ = "0.3.1a5" diff --git a/docs/en/guide/install-python.md b/docs/en/guide/install-python.md index 21ba7a76..157ec861 100644 --- a/docs/en/guide/install-python.md +++ b/docs/en/guide/install-python.md @@ -1,72 +1,50 @@ # Install the Python packages -The immutable source recipe below installs the tested 0.3.0 snapshot. The current 0.3.1a2 alpha candidate is documented separately below and is usable from PyPI only after its publication and public readback succeed. Package names alone do not prove publication. The CLI is installed separately from its own repository. - -## Paired immutable source - -Use a virtual environment with Python 3.10 or newer. This tested immutable implementation includes standard sync/async clients, native provider/server extensions, the server startup acknowledgement fix, strict workflows and the base YAML parser. It does not claim to be the latest main commit. +Use Python 3.10 or newer and a virtual environment: ```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 venv .venv +# Linux or macOS: +source .venv/bin/activate +# Windows PowerShell: .venv\Scripts\Activate.ps1 +python -m pip install --index-url https://pypi.org/simple 'agent-sandbox-client==0.3.1a5' python -m pip check -python -c "import agent_sandbox, agent_sandbox.server; from importlib.metadata import version; print(version('agent-sandbox-client'), version('agent-sandbox-server'))" ``` -Both versions are 0.3.0 and must match. The client has a hard same-version server dependency for local server and declarative helpers; explicitly installing both source distributions prevents pip from seeking the unavailable server on an index. Do not install the unrelated `agent-sandbox` distribution. - -## Optional extras +This installs the alpha client and its required same-version `agent-sandbox-server` dependency. The import namespace is `agent_sandbox`; the unrelated PyPI distribution named `agent-sandbox` is not this project. -Workflow YAML loading and the declarative decorator are part of the base client; there is no declarative extra. - -For all extras, retain the same server URL and use the client extra on its direct reference: +Check the installed pair: ```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[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk" +python -c "from importlib.metadata import version; print(version('agent-sandbox-client'), version('agent-sandbox-server'))" ``` -Replace `[all]` with `[mcp]`, `[session]` or `[fast]` for that subset. MCP needs its extra; Browser automation requires separately installed Playwright in the image. +Install the [abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox) separately. For the template workflows in this guide, use CLI 0.4.16 or newer and configure the selected provider before creating a sandbox. -## Server-only image installation +## Optional dependencies ```bash -python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" +python -m pip install 'agent-sandbox-client[all]==0.3.1a5' ``` -The in-sandbox service and the local client have different roles; installing the server does not create a sandbox. - -## Current development checkout +Replace `[all]` with `[mcp]`, `[session]` or `[fast]` for that subset. Workflow YAML and the declarative decorator belong to the base client; they need no extra. Browser automation requires Playwright installed inside the sandbox image. -From this repository root, in an isolated environment: +## Server-only installation inside an image ```bash -python -m pip install -e ./server-sdk -e "./client-sdk[dev]" -python -m pip check +python -m pip install 'agent-sandbox-server==0.3.1a5' ``` -This uses the checked-out revision rather than the immutable example above. Record its commit for reproducibility. Run examples only after configuring the required provider; an installation pass is not cloud/provider/model acceptance. Diagnose dependency conflicts in a fresh environment before reinstalling both matched distributions. - -## Maintainer publication checks +The server runs the application inside an image. Installing it does not create a sandbox. See the [server guide](server-sdk.md) to register commands and start the service. -Publish both distributions from a matching `v` tag. The workflow first runs -the reusable CI suite against that same tag checkout; publication depends on its success. -The release workflow -builds one wheel/sdist pair per package, installs the exact wheel pair in a clean -environment, and preserves the candidate artifact. A manual run defaults to dry-run -and still requires the version tag. Before upload, any existing PyPI file must match -the candidate SHA-256; `skip-existing` alone is not verification. Server uploads before -client. After upload, the workflow checks public file digests and installs the exact client from the public index in a fresh environment, validates the automatically installed matching server, and runs `pip check`. A failed readback means publication -has not been verified; preserve the candidate for recovery instead of rebuilding silently. -This workflow does not replace required CI, reviews or real-backend acceptance. +## Development from a checkout -## Optional alpha release - -The 0.3.1a2 candidate is an opt-in prerelease. Once its public release is verified, install the exact client version below; its matching server is a required dependency. Until publication completes, the immutable source recipe above remains available. Node provider doctor requires the companion CLI initialize endpoint (planned CLI 0.4.11); 0.4.10 does not support it. This is not a production-readiness claim. +From the repository root, install both local distributions together: ```bash -python -m pip install 'agent-sandbox-client==0.3.1a2' +git rev-parse HEAD +python -m pip install -e ./server-sdk -e './client-sdk[dev]' python -m pip check ``` + +Record the commit when reproducing a source installation; both packages come from that same checkout. To reproduce a specific release, check out its tag first. Contributor validation and publication requirements are in [CONTRIBUTING](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/.github/CONTRIBUTING.md). diff --git a/docs/zh/guide/install-python.md b/docs/zh/guide/install-python.md index 9a624a7a..b558200b 100644 --- a/docs/zh/guide/install-python.md +++ b/docs/zh/guide/install-python.md @@ -1,69 +1,50 @@ # 安装 Python 配套包 -下面的固定源码方案安装已验证的0.3.0快照；当前0.3.1a2 alpha 候选的说明见后文，只有发布及公开回读成功后才能从 PyPI 安装。包名存在于项目中不等于已发布。CLI 从其独立仓库安装。 - -## 固定提交的配套源码 - -使用 Python 3.10或更高版本及虚拟环境。此已验证的固定实现包含标准同步/异步客户端、原生 Provider/server 扩展及服务启动确认修复；并不声称它是最新主线提交。 +使用 Python 3.10 或更高版本及虚拟环境： ```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 venv .venv +# Linux 或 macOS： +source .venv/bin/activate +# Windows PowerShell：.venv\Scripts\Activate.ps1 +python -m pip install --index-url https://pypi.org/simple 'agent-sandbox-client==0.3.1a5' python -m pip check -python -c "import agent_sandbox, agent_sandbox.server; from importlib.metadata import version; print(version('agent-sandbox-client'), version('agent-sandbox-server'))" ``` -两个版本均为0.3.0，必须一致。客户端的本地服务端和声明式辅助功能需要同版本服务端，因此将它列为必需依赖；同时指定两个源码发行包，避免 pip 去索引寻找尚未发布的服务端。不要安装无关的 `agent-sandbox` 发行包。 - -## 可选 extras +此命令安装 alpha 客户端，并自动安装同版本的必需依赖 `agent-sandbox-server`。导入名为 `agent_sandbox`；PyPI 上名为 `agent-sandbox` 的发行包是另一个无关项目。 -工作流 YAML 加载和声明式装饰器属于基础客户端，不再提供 declarative extra。 - -保留同一个服务端 URL，在客户端直接引用上选择 extra；全量依赖使用： +检查安装的配套版本： ```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[all] @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=client-sdk" +python -c "from importlib.metadata import version; print(version('agent-sandbox-client'), version('agent-sandbox-server'))" ``` -可把 `[all]` 换成 `[mcp]`、`[session]` 或 `[fast]`。MCP 需要相应 extra；浏览器自动化还需在镜像内单独安装 Playwright。 +[abx CLI](https://github.com/Alibaba-Agent-Sandbox/agent-sandbox) 需要独立安装。本指南中的模板工作流使用 CLI 0.4.16 或更高版本；创建沙箱前先配置所选平台。 -## 镜像内只安装服务端 +## 可选依赖 ```bash -python -m pip install "agent-sandbox-server @ https://github.com/Alibaba-Agent-Sandbox/python-sdk/archive/fee74e631d9cfc3488fd41f853ca6dafc1277784.tar.gz#subdirectory=server-sdk" +python -m pip install 'agent-sandbox-client[all]==0.3.1a5' ``` -沙箱内服务端和本地客户端职责不同，安装服务端不会创建沙箱。 - -## 当前开发检出 +可把 `[all]` 换成 `[mcp]`、`[session]` 或 `[fast]`。工作流 YAML 和声明式装饰器属于基础客户端，无需 extra。浏览器自动化需要在沙箱镜像内安装 Playwright。 -在隔离环境中，从本仓库根目录运行： +## 镜像内只安装服务端 ```bash -python -m pip install -e ./server-sdk -e "./client-sdk[dev]" -python -m pip check +python -m pip install 'agent-sandbox-server==0.3.1a5' ``` -此时使用实际检出的源码，而非上面的固定示例，应记录提交以便复现。配置所需厂商后再运行示例；安装通过不等于云端、厂商或模型验收通过。依赖冲突优先在新环境中定位，再同时重装配套发行包。 - -## 维护者发布检查 +服务端负责在镜像内运行应用，安装它不会创建沙箱。注册命令与启动服务见[服务端指南](server-sdk.md)。 -两个发行包必须从匹配的 `v` 标签发布。先对同一标签检出执行复用 CI， -只有 CI 成功才进入发布任务。工作流为每个包构建一次 wheel/sdist， -在新环境安装这对实际 wheel，并保存候选产物。手动运行默认 dry-run，同样要求选择 -版本标签。上传前 PyPI 已存在的文件必须与候选 SHA-256 一致，不能只靠 `skip-existing` -宣称验证成功。先上传 server，再上传 client；之后回读公开文件摘要，并从公开索引 -在新环境只安装固定版本 client，验证 server 自动依赖并运行 `pip check`。回读失败表示发布尚未验证，应保留候选产物用于恢复， -不要静默重新构建。该工作流不能替代必需 CI、评审及真实后端验收。 +## 从检出源码进行开发 -## 可选 alpha 预发布 - -0.3.1a2 是需显式选择的 alpha 候选。公开发布验证完成后，可使用下面的精确版本安装；同版本 server 由依赖自动安装。发布完成前，仍可使用上面的固定源码方案。Node provider doctor 需要配套 CLI initialize 接口（计划为 CLI 0.4.11），0.4.10 不支持。测试版不代表所有能力生产就绪。 +在仓库根目录同时安装两个本地发行包： ```bash -python -m pip install 'agent-sandbox-client==0.3.1a2' +git rev-parse HEAD +python -m pip install -e ./server-sdk -e './client-sdk[dev]' python -m pip check ``` + +复现源码安装时记录提交，两个包都使用同一份检出。复现特定发行版本时，先检出对应 tag。贡献者验证与发布要求见 [CONTRIBUTING](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/.github/CONTRIBUTING.md)。 diff --git a/scripts/local-paths.allowlist b/scripts/local-paths.allowlist index 44f12e1d..53f97406 100644 --- a/scripts/local-paths.allowlist +++ b/scripts/local-paths.allowlist @@ -21,3 +21,8 @@ docs/en/design/repository-layout.md # This note describes the patterns the guard rejects. .agents/notes/implemented/process/*-open-source-hygiene.md + +# The bilingual install guide creates this virtualenv immediately before activation; +# this is a reproducible user command, not an assumed developer-machine interpreter. +docs/en/guide/install-python.md|^source [.]venv/bin/activate$ +docs/zh/guide/install-python.md|^source [.]venv/bin/activate$ diff --git a/server-sdk/README.md b/server-sdk/README.md index d628ff31..5fe6aae5 100644 --- a/server-sdk/README.md +++ b/server-sdk/README.md @@ -1,6 +1,6 @@ # agent-sandbox-server -This package is the opt-in **0.3.1a2 alpha** candidate. Use its exact PyPI version after verified publication; before that, use the [tested paired source recipe](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md). Alpha publication does not establish every provider or template as production-ready. +Install the current alpha with `--pre`; use the [installation guide](https://github.com/Alibaba-Agent-Sandbox/python-sdk/blob/main/docs/en/guide/install-python.md) for a pinned version and environment setup. **Server SDK.** This package runs *inside* a sandbox image. It is the HTTP service the image starts (default port 9000). It does not create the sandbox. Creating and calling the sandbox is the [client SDK](https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/client-sdk/README.md) or the `abx` CLI. Guide: [Server SDK](https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/docs/en/guide/server-sdk.md). @@ -12,7 +12,7 @@ Import path: `agent_sandbox.server` (a namespace shared with `agent-sandbox-clie ## Install ```bash -python -m pip install 'agent-sandbox-server==0.3.1a2' +python -m pip install --upgrade --pre agent-sandbox-server python -m pip check ``` diff --git a/server-sdk/src/agent_sandbox/server/_version.py b/server-sdk/src/agent_sandbox/server/_version.py index 7d2cb4b3..ea816294 100644 --- a/server-sdk/src/agent_sandbox/server/_version.py +++ b/server-sdk/src/agent_sandbox/server/_version.py @@ -1 +1 @@ -__version__ = "0.3.1a4" +__version__ = "0.3.1a5"