Skip to content

Commit d8dc1eb

Browse files
anycodesanycodes
committed
Add a cloud end-to-end practice page for the Python SDK examples.
The page points at the quickstart and compat-demo scripts on the default provider and links the Agents API guide instead of repeating that case.
1 parent 98532eb commit d8dc1eb

6 files changed

Lines changed: 136 additions & 0 deletions

File tree

‎docs/en/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Easy Sandbox is a cloud sandbox SDK built on Alibaba Cloud Function Compute, pro
3030
|-------|-------------|
3131
| [Agents API](guide/agents-api.md) | HTTP sessions for Codex and Qwen Code. Not the built-in agent sugar. CLIs install on demand. Includes the complete case |
3232
| [Getting Started](guide/getting-started.md) | Install, configure, first sandbox *(coming soon)* |
33+
| [Cloud end-to-end practice](guide/cloud-examples.md) | Run the quickstart and compat demos on the default provider. The Agents API case stays on its own page |
3334
| [Authentication](guide/authentication.md) | API Key / AK-SK authentication *(coming soon)* |
3435
| [SDK Usage](guide/sdk-usage.md) | Python SDK complete usage *(coming soon)* |
3536
| [CLI Tutorial](../../../cli/docs/en/guide/cli-tutorial.md) *(`cli` repository)* | CLI quick start *(coming soon)* |

‎docs/en/guide/cloud-examples.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Cloud end-to-end practice
2+
3+
Run the repository's cloud examples against a real sandbox on the default provider, **Alibaba Cloud Express** (`alicloud-express`). Do not push an image to ACR.
4+
5+
> 中文版: [../../zh/guide/cloud-examples.md](../../zh/guide/cloud-examples.md)
6+
7+
The Agents API case is not repeated here. For the request sequence, the local stand-in CLIs, and a run that does not read a model key, see [Agents API](agents-api.md). The Chinese page is [Agents API（中文）](../../zh/guide/agents-api.md).
8+
9+
## Setup
10+
11+
The client reads `EBX_SANDBOX_API_KEY`. The current client does not treat `E2B_API_KEY` as the sandbox key.
12+
13+
```bash
14+
pip install "easy-sandbox[declarative]"
15+
export EBX_SANDBOX_API_KEY="your-api-key"
16+
```
17+
18+
When `EBX_PROVIDER` is unset, `Sandbox.create` uses `alicloud-express`. The scripts below pass `timeout` to `Sandbox.create` (sandbox TTL, in seconds, from 60 to 900) and destroy the sandbox when the `async with` block or the `@sandbox` decorator finishes.
19+
20+
From this repo, before `pip install`:
21+
22+
```bash
23+
export PYTHONPATH=client-sdk/src:server-sdk/src
24+
```
25+
26+
## Run these
27+
28+
From the `python-sdk` directory:
29+
30+
```bash
31+
python examples/quickstart/03_web_service.py
32+
python examples/quickstart/04_data_analysis.py
33+
python examples/quickstart/05_decorator_usage.py
34+
python examples/compat-demos/comparison.py
35+
python examples/compat-demos/e2b_data_analysis.py
36+
python examples/compat-demos/e2b_web_scraper.py
37+
python examples/compat-demos/modal_compute.py
38+
python examples/compat-demos/modal_data_analysis.py
39+
```
40+
41+
| Script | What it does in the cloud |
42+
|---|---|
43+
| `examples/quickstart/03_web_service.py` | Template `node-web`. Writes an Express app, runs `npm install`, curls `localhost:3000` inside the sandbox |
44+
| `examples/quickstart/04_data_analysis.py` | Template `base`. Installs pandas, analyzes a CSV, then `run_code()` for the top three rows |
45+
| `examples/quickstart/05_decorator_usage.py` | `@sandbox` on `code-interpreter-v1`: π, a pandas summary, Fibonacci, environment variables |
46+
| `examples/compat-demos/comparison.py` | The same tasks with imperative `Sandbox.create` and with `@sandbox` |
47+
| `examples/compat-demos/e2b_data_analysis.py` | Imperative: upload a CSV, write a pandas report, read the report back |
48+
| `examples/compat-demos/e2b_web_scraper.py` | Imperative: request `https://example.com` from inside the sandbox |
49+
| `examples/compat-demos/modal_compute.py` | `@sandbox`: Monte Carlo π, matrix multiply, distribution fit |
50+
| `examples/compat-demos/modal_data_analysis.py` | `@sandbox`: sales summary, data quality, product rank |
51+
52+
On `base`, `run_code()` in `04_data_analysis.py` can see HTTP 404 from the code-interpreter port. The client falls back to the shell, and the example still prints the table.
53+
54+
If create fails, read the error code on the exception (a missing template is `E2001`) and stop that example. Do not switch to pushing an image.
55+
56+
## Two agent examples
57+
58+
Both can start without a paid model key. Set a model key only when you want a real model call.
59+
60+
- `examples/agents/codex_agent.py` uses template `codex`. If that template is not on the account, `Sandbox.create` fails with `E2001` and the script's simulation branch never runs. `OPENAI_API_KEY` is required only for the live model branch.
61+
- `examples/agents/browser_automation.py` does not read a model key. It `pip install`s Playwright on `base`, then runs `playwright install chromium`. If `playwright` is not on `PATH`, `commands.run` raises `E3006` (`exec: "playwright": executable file not found in $PATH`). The `async with` block still destroys the sandbox.
62+
63+
For Codex and Qwen Code HTTP sessions inside a sandbox, use `examples/agents/complete_case.py` from [Agents API](agents-api.md).

‎docs/en/guide/testing-e2e.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,7 @@ A change is done when all of the following hold:
3737
6. No sandbox or template is leaked.
3838

3939
The full rules and the ADR and evidence templates: [`.agents/notes/DEFINITION-OF-DONE.md`](../../../.agents/notes/DEFINITION-OF-DONE.md).
40+
41+
## Cloud example practice
42+
43+
Outside the test suite, the walkthrough that runs the example scripts on the default provider is [Cloud end-to-end practice](cloud-examples.md). The Agents API case is not on that page; see [Agents API](agents-api.md).

‎docs/zh/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ Easy Sandbox 是基于阿里云函数计算的云端沙箱 SDK，提供 E2B 兼
2828
|------|------|
2929
| [Agents API](guide/agents-api.md) | Codex 与 Qwen Code 的 HTTP 会话。不是内置 Agent。CLI 按需安装。含完整案例 |
3030
| [快速开始](guide/getting-started.md) | 安装、配置、第一个沙箱 |
31+
| [云上端到端练习](guide/cloud-examples.md) | 在默认提供方上跑 quickstart 与 compat-demos。Agents API 案例见专页 |
3132
| [认证配置](guide/authentication.md) | API Key / AK-SK 双认证模式 |
3233
| [SDK 使用](guide/sdk-usage.md) | Python SDK 完整用法 |
3334
| [CLI 教程](../../../cli/docs/zh/guide/cli-tutorial.md) *（`cli` 仓库）* | 命令行快速上手 |

‎docs/zh/guide/cloud-examples.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# 云上端到端练习
2+
3+
在默认提供方 **阿里云极速版**（`alicloud-express`）上，用真实沙箱把仓库里的云端示例跑一遍。不需要把镜像推到 ACR。
4+
5+
> English: [../../en/guide/cloud-examples.md](../../en/guide/cloud-examples.md)
6+
7+
Agents API 的完整案例不在本页。那一组请求、本地替身 CLI，以及不读取模型密钥的跑法，见 [Agents API](agents-api.md)。
8+
9+
## 准备
10+
11+
客户端读取 `EBX_SANDBOX_API_KEY`。旧名字 `E2B_API_KEY` 不会被当前客户端当成沙箱密钥。
12+
13+
```bash
14+
pip install "easy-sandbox[declarative]"
15+
export EBX_SANDBOX_API_KEY="your-api-key"
16+
```
17+
18+
未设置 `EBX_PROVIDER` 时，`Sandbox.create` 使用 `alicloud-express`。下面的脚本自己把 `timeout` 传给 `Sandbox.create`（这是沙箱 TTL，单位秒，从 60 到 900），并在 `async with` 或 `@sandbox` 结束时销毁沙箱。
19+
20+
在本仓库里、尚未 `pip install` 时，把源码放到 `PYTHONPATH`：
21+
22+
```bash
23+
export PYTHONPATH=client-sdk/src:server-sdk/src
24+
```
25+
26+
## 照着跑
27+
28+
在 `python-sdk` 目录：
29+
30+
```bash
31+
python examples/quickstart/03_web_service.py
32+
python examples/quickstart/04_data_analysis.py
33+
python examples/quickstart/05_decorator_usage.py
34+
python examples/compat-demos/comparison.py
35+
python examples/compat-demos/e2b_data_analysis.py
36+
python examples/compat-demos/e2b_web_scraper.py
37+
python examples/compat-demos/modal_compute.py
38+
python examples/compat-demos/modal_data_analysis.py
39+
```
40+
41+
| 脚本 | 它在云上做什么 |
42+
|---|---|
43+
| `examples/quickstart/03_web_service.py` | 模板 `node-web`。写入 Express 应用，`npm install`，在沙箱内请求 `localhost:3000` |
44+
| `examples/quickstart/04_data_analysis.py` | 模板 `base`。安装 pandas，分析 CSV，再用 `run_code()` 取前三名 |
45+
| `examples/quickstart/05_decorator_usage.py` | `@sandbox`，模板 `code-interpreter-v1`。π、pandas 摘要、斐波那契、环境变量 |
46+
| `examples/compat-demos/comparison.py` | 同一任务的命令式 `Sandbox.create` 与 `@sandbox` |
47+
| `examples/compat-demos/e2b_data_analysis.py` | 命令式：上传 CSV，pandas 出报告，再把报告读回来 |
48+
| `examples/compat-demos/e2b_web_scraper.py` | 命令式：在沙箱里请求 `https://example.com` |
49+
| `examples/compat-demos/modal_compute.py` | `@sandbox`：蒙特卡洛 π、矩阵乘、分布拟合 |
50+
| `examples/compat-demos/modal_data_analysis.py` | `@sandbox`：销售汇总、数据质量、产品排名 |
51+
52+
`04_data_analysis.py` 在 `base` 上调用 `run_code()` 时，代码解释器端口可能返回 HTTP 404。客户端会改走 shell，示例仍打印表格。
53+
54+
创建失败时看异常上的错误码（例如模板不存在是 `E2001`），停掉这个示例，不要改去推镜像。
55+
56+
## 两个 Agent 示例
57+
58+
它们不需要付费模型密钥也能启动。模型密钥只在你要调用真实模型时才设置。
59+
60+
- `examples/agents/codex_agent.py` 使用模板 `codex`。账户上没有这个模板时，`Sandbox.create` 以 `E2001` 失败，走不到脚本里的模拟分支。真实模型调用才需要 `OPENAI_API_KEY`。
61+
- `examples/agents/browser_automation.py` 不读取模型密钥。它在 `base` 里 `pip install playwright`，再执行 `playwright install chromium`。若 `playwright` 不在 `PATH` 上，`commands.run` 抛出 `E3006`（`exec: "playwright": executable file not found in $PATH`）。`async with` 仍会销毁沙箱。
62+
63+
沙箱里的 Codex / Qwen Code HTTP 会话，用 [Agents API](agents-api.md) 的 `examples/agents/complete_case.py`。

‎docs/zh/guide/testing-e2e.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,7 @@ make e2e-cleanup # 清理遗留资源的 dry-run janitor;ARGS=--yes 才
3737
6. 没有遗留沙箱或模板。
3838

3939
完整规则以及 ADR 与证据模板见 [`.agents/notes/DEFINITION-OF-DONE.md`](../../../.agents/notes/DEFINITION-OF-DONE.md)。
40+
41+
## 云上示例练习
42+
43+
测试套件之外，按脚本在默认提供方上走一遍的说明见 [云上端到端练习](cloud-examples.md)。Agents API 的完整案例不在那一页，见 [Agents API](agents-api.md)。

0 commit comments

Comments
 (0)