@@ -36,7 +36,7 @@ the server only ships `easy_sandbox/server/`) and are **released in lockstep** w
 - **Declarative decorator** — `@sandbox` turns a plain function into a remote sandbox execution with automatic serialisation.
 - **Session persistence** — save and restore sandbox state across runs.
 - **E2B compatibility layer** — drop-in replacement for projects already using the E2B SDK.
-- **Agents API** — in-sandbox HTTP sessions for Codex and Qwen Code only. Install a CLI when you call it; the base image does not carry both. Guide and complete case: [Agents API](docs/en/guide/agents-api.md).
+- **Agents API** — in-sandbox HTTP sessions. Codex and Qwen Code are supported today. Install a CLI when you call it; the base image does not carry both. Guide and complete case: [Agents API](docs/en/guide/agents-api.md).
 
 ## Installation
 
 
@@ -35,7 +35,7 @@ Node.js 项目，位于 [`cli`](https://github.com/Easy-Sandbox/easy-sandbox)
 - **声明式装饰器** —— `@sandbox` 将普通函数变为远程沙箱执行，自动序列化。
 - **会话持久化** —— 跨运行保存和恢复沙箱状态。
 - **E2B 兼容层** —— 已使用 E2B SDK 的项目可直接替换。
-- **Agents API** —— 沙箱内 HTTP 会话，只接 Codex 和 Qwen Code。CLI 按需安装，不打进基础镜像。说明和完整案例见 [Agents API](docs/zh/guide/agents-api.md)。
+- **Agents API** —— 沙箱内 HTTP 会话。目前支持 Codex 和 Qwen Code。CLI 按需安装，不打进基础镜像。说明和完整案例见 [Agents API](docs/zh/guide/agents-api.md)。
 
 ## 安装
 
 
@@ -1,6 +1,9 @@
 # Built-in Agent High-Level API Design
 
-> Easy Sandbox built-in agents adopt a minimalist architecture: AI CLI tools (Codex, etc.) are pre-installed in sandbox templates, and the SDK Agent API is simply syntactic sugar wrapping `commands.run()`. The SDK has zero LLM dependencies, keeping it lightweight.
+> This is the design for `sb.agent.*`, which is sugar over `commands.run()`. It is not the HTTP Agents API.
+> The Agents API (`/v1/agents/sessions`; Codex and Qwen Code are supported today) is [Agents API](../guide/agents-api.md). The base image does not preinstall those CLIs. Install the one you call. See the [`agents-cli`](../../examples/templates/agents-cli/README.md) template.
+
+> The rest of this page still describes an earlier idea that baked Codex into a template. The product does not put Codex and Qwen Code into the base image together.
 
 ---
 
 
@@ -1,6 +1,6 @@
 # Agents API
 
-HTTP sessions inside the sandbox. This slice hosts **Codex** and **Qwen Code** only. The base image does not install either CLI. Install the one you are about to call.
+HTTP sessions inside the sandbox. Codex and Qwen Code are supported today. The base image does not install either CLI. Install the one you are about to call.
 
 This is not the [built-in agent design](../design/built-in-agents.md). That page is `sb.agent.*`, sugar over `commands.run()`. The Agents API is a different set of routes: `/v1/agents/sessions`.
 
@@ -17,7 +17,7 @@ npm install -g @qwen-code/qwen-code   # binary name: qwen
 
 Codex reads `OPENAI_API_KEY` or `CODEX_API_KEY` when it actually calls a model. Qwen Code reads `OPENAI_API_KEY`. Inject the key when the sandbox is created. Do not bake it into the image, and do not put it in the case below.
 
-The [agents-cli](https://github.com/Easy-Sandbox/awesome-templates/tree/main/agents-cli) template only turns the `agents` group on. Its Dockerfile leaves the one `npm install` line for you to add.
+The [agents-cli](https://github.com/Easy-Sandbox/awesome-templates/tree/main/agents-cli) template does not turn on `file_ops` or `process`. `groups.agents: true` is only the gate. `endpoints` sets `*` to `enabled: false`, then turns on `agents_sessions_create`, `agents_sessions_events_create`, `agents_sessions_items_list`, and `agents_runtimes_list` one by one. `POST /shell` and `POST /v1/agents` (definitions) stay 404. The Dockerfile leaves the one `npm install` line for the CLI you call.
 
 ## Not the built-in agent API
 
@@ -30,13 +30,13 @@ The [agents-cli](https://github.com/Easy-Sandbox/awesome-templates/tree/main/age
 
 ## Complete case
 
-The case starts a local server and puts two stand-in programs named `codex` and `qwen` on `PATH`. It does not read a model key. The stand-ins prove the HTTP session. After the `npm install` lines above, the same requests run the real CLIs.
+The case starts a local server and places programs named `codex` and `qwen` on `PATH` so the requests and responses can be shown without a model key. After the `npm install` lines above, the same requests run the real CLIs.
 
 ```bash
 python examples/agents/complete_case.py
 ```
 
-Ran locally on 2026-10-13, exit code 0. The transcript below keeps the stable parts. Session ids change every run.
+The shapes below are what the server returns. The server assigns the session id.
 
 A model id such as `gpt-5` does not select a CLI:
 
@@ -46,7 +46,7 @@ X-Easy-Sandbox-Local: 1
 code: agents.adapter_required
 ```
 
-`claude-code` is outside this slice:
+An adapter name that is not supported today, for example `claude-code`:
 
 ```text
 POST /v1/agents/sessions  adapter=claude-code  404
@@ -56,7 +56,7 @@ code: agents.not_implemented_locally
 message: adapter 'claude-code' is not available in this slice (codex, qwen-code)
 ```
 
-`GET /v1/agents/runtimes` lists only `codex` and `qwen-code`, each with `install_steps` (`npm install -g ...`). `installed` is whether that binary is on this process's `PATH` right now.
+`GET /v1/agents/runtimes` currently returns `codex` and `qwen-code`, each with `install_steps` (`npm install -g ...`). `installed` is whether that binary is on this process's `PATH`.
 
 One Codex turn:
 
 
@@ -77,7 +77,7 @@ sandbox = await Sandbox.connect("sbx-xxxx", sandbox_api_key="your-api-key")
 
 ## AK/SK Alibaba Cloud Extended Authentication 🧪
 
-> **⚠️ Experimental Feature**: The AK/SK → API Key token exchange framework is implemented in the SDK (`transport/auth.py`), but the token exchange endpoint’s action name (`CreateApiKey`) and response field parsing **are still pending FC platform team confirmation**. TTL (3600s) and early refresh time (300s) are assumed values, not validated against a real endpoint. This feature can be used for local debugging; **API Key authentication is still recommended for production environments**.
+> **⚠️ Experimental Feature**: The AK/SK → API Key token exchange framework is implemented in the SDK (`transport/auth.py`), but the token exchange endpoint’s action name (`CreateApiKey`) and response field parsing **are still pending FC platform team confirmation**. TTL (3600s) and the 300s early refresh are placeholders until the platform confirms the endpoint. Use it for local debugging; **API Key authentication is still recommended for production**.
 
 AK/SK mode uses an Alibaba Cloud AccessKey pair to obtain a temporary API Key via token exchange (designed TTL 3600 seconds, auto-refreshed 300 seconds before expiry).
 
 
@@ -26,7 +26,7 @@ Or set `server.groups` in the template policy (`process: false`, and so on). `co
 
 The Agents routes stay off until the process is started with `EBX_SERVER_ENABLED_GROUPS=agents` (or `enable_group(CapabilityGroup.AGENTS)` before `serve()`). With the group off, those paths answer 404 and the body says the route is disabled.
 
-This slice hosts Codex and Qwen Code only. Checklist, the local header, and the 404s: [Hosted agents — Best practices](hosted-agents.md#best-practices).
+Codex and Qwen Code are supported today. Checklist, the local header, and the 404s: [Hosted agents — Best practices](hosted-agents.md#best-practices).
 
 ## Secrets are not echoed
 
 
@@ -171,7 +171,7 @@ asyncio.run(main())
 
 ---
 
-The sandbox server can also host coding-agent CLIs. This slice is Codex (`codex`, npm package `@openai/codex`) and Qwen Code (`qwen`, npm package `@qwen-code/qwen-code`) only, on `/v1/agents/sessions`, and only after `EBX_SERVER_ENABLED_GROUPS` includes `agents`. See [Hosted agents](hosted-agents.md).
+The sandbox server can also host coding-agent CLIs. Codex (`codex`, npm package `@openai/codex`) and Qwen Code (`qwen`, npm package `@qwen-code/qwen-code`) are supported today, on `/v1/agents/sessions`, after `EBX_SERVER_ENABLED_GROUPS` includes `agents`. See [Hosted agents](hosted-agents.md).
 
 ## Next Steps
 
 
@@ -2,7 +2,7 @@
 
 The user guide and the runnable case are in [Agents API](agents-api.md). This page is the route reference.
 
-This slice hosts **Codex** and **Qwen Code** only. Claude Code, Cursor, Qoder and the generic command adapter are not served here. Naming any other adapter returns HTTP 404 `not_found_error` with `x-should-retry: false`.
+Codex and Qwen Code are supported today. Adapter names that are not supported yet, including Claude Code, Cursor, Qoder, and the generic command adapter, return HTTP 404 `not_found_error` with `x-should-retry: false`.
 
 The routes live on the sandbox server (`easy_sandbox.server`), in the opt-in `agents` capability group. They stay **off** until `EBX_SERVER_ENABLED_GROUPS` includes `agents`. With the group disabled, the same paths answer 404 and the body says the route is disabled.
 
@@ -15,7 +15,7 @@ The template server listens on **port 9000**. Point an OpenAI-shaped client at `
 
 ## Best practices
 
-* Host **Codex** and **Qwen Code** only. A body that names Claude Code, Cursor, Qoder, or any other adapter is HTTP 404 `not_found_error` with `x-should-retry: false`.
+* Codex and Qwen Code are supported today. A body that names an adapter that is not supported yet is HTTP 404 `not_found_error` with `x-should-retry: false`.
 * Treat every response as local. Read the header `X-Easy-Sandbox-Local: 1` (errors included). `x_easy_sandbox.compute` is `local_process`, `local_state`, or `none`.
 * Do not call `POST /v1/responses/input_tokens`. It is 404 `agents.not_implemented_locally` with `x-should-retry: false`. No tokenizer matches the model the CLI will call.
 * Leave the group off until a session needs it. Start the process with `EBX_SERVER_ENABLED_GROUPS=agents`.
@@ -155,4 +155,4 @@ Webhook endpoints (`/v1/webhook_endpoints`, create, retrieve, update, list, dele
 
 Each answers `404`, `type: not_found_error`, `code: agents.not_implemented_locally`, `x-should-retry: false`, `X-Easy-Sandbox-Local: 1`.
 
-Clients that only demonstrate the calls, against a server you already started: [hosted_codex.py](../../../examples/agents/hosted_codex.py) and [hosted_qwen.py](../../../examples/agents/hosted_qwen.py). [local_files_and_session.py](../../../examples/agents/local_files_and_session.py) uploads one file and runs one session against a local server, using the fake CLI (no model API key). See [examples/agents/README.md](../../../examples/agents/README.md).
+Clients that only demonstrate the calls, against a server you already started: [hosted_codex.py](../../../examples/agents/hosted_codex.py) and [hosted_qwen.py](../../../examples/agents/hosted_qwen.py). [local_files_and_session.py](../../../examples/agents/local_files_and_session.py) uploads one file and opens one session against a local server. It places a local program named `codex` on `PATH` and does not read a model API key. See [examples/agents/README.md](../../../examples/agents/README.md).
@@ -1,6 +1,9 @@
 # 内置 Agent 高级 API 设计
 
-> Easy Sandbox 内置 Agent 采用极简架构：沙箱模板内预装 AI CLI 工具（Codex 等），SDK Agent API 只是 `commands.run()` 的语法糖封装。SDK 零 LLM 依赖，保持轻量。
+> 这是 `sb.agent.*` 的设计稿，本质是 `commands.run()` 的语法糖。它不是 HTTP Agents API。
+> Agents API（`/v1/agents/sessions`，目前支持 Codex 和 Qwen Code）见 [Agents API](../guide/agents-api.md)。基础镜像不预装这些 CLI；要用哪一个再安装哪一个，见模板 [`agents-cli`](../../examples/templates/agents-cli/README.md)。
+
+> 下文仍保留早期「模板内预装 Codex」的写法，用来说明语法糖设想。当前产品不把 Codex 和 Qwen Code 一起打进基础镜像。
 
 ---
 
 
@@ -268,7 +268,7 @@ def run_app():
 
 ## 范式三：内置 Agent 模式
 
-这一节是 `sb.agent.*` 的设计稿，不是 Agents API。Agents API 是沙箱里的 HTTP 会话（`/v1/agents/sessions`），只接 Codex 和 Qwen Code，CLI 按需安装。用法和完整案例见 [Agents API](../guide/agents-api.md)。
+这一节是 `sb.agent.*` 的设计稿，不是 Agents API。Agents API 是沙箱里的 HTTP 会话（`/v1/agents/sessions`）。目前支持 Codex 和 Qwen Code，CLI 按需安装。用法和完整案例见 [Agents API](../guide/agents-api.md)。
 
 全新设计 — SDK 内置预配置的 AI Agent，一行代码完成复杂任务。