zakahan · Oct 26, 2026 · Oct 26, 2026
diff --git a/docs/content/docs/framework/agent/skills.en.mdx b/docs/content/docs/framework/agent/skills.en.mdx
@@ -2,7 +2,7 @@
 title: "Skills"
 ---
 
-Skills are reusable "prompt packages" that inject specific domain knowledge, operating procedures, and scripts into an Agent. For local skill loading and execution, the recommended integration is Google ADK's official `load_skill_from_dir` / `SkillToolset` path. VeADK's legacy `Agent(skills=..., skills_mode="local")` local entry point remains compatible, but is deprecated. The `skills_sandbox` and `aio_sandbox` modes keep their existing behavior.
+Skills are reusable "prompt packages" that inject specific domain knowledge, operating procedures, and scripts into an Agent. For local skill loading and execution, the recommended integration is Google ADK's official `load_skill_from_dir` / `SkillToolset` path. VeADK's legacy `Agent(skills=..., skills_mode="local")` local entry point remains compatible, but is deprecated. `skills_sandbox` executes through cloud Skill Spaces; `aio_sandbox` loads skills and executes file and Shell tools in a bound sandbox.
 
 ## Recommended: ADK SkillToolset
 
@@ -70,7 +70,7 @@ The `skills` parameter still supports three skill execution modes. Only the lega
 | :- | :- |
 | `local` | Deprecated. Skills are loaded by VeADK's legacy `skills_tool` plus file/Shell helper tools; migrate to ADK `SkillToolset` for local execution. |
 | `skills_sandbox` | Skills are hosted in a cloud Skill Space and executed in a sandbox through the `execute_skills` tool. |
-| `aio_sandbox` | All-in-one sandbox mode, suitable for the AgentKit-hosted tool runtime. |
+| `aio_sandbox` | Runtime owns inference; a bound All-in-one sandbox provides Skill files and basic tools. `skills` contains absolute sandbox directories. |
 
 When `skills_mode` is not set explicitly, VeADK infers it from the runtime environment: local runs default to `local`; in the AgentKit tool runtime, it automatically selects `skills_sandbox` or `aio_sandbox` based on the tool type.
 
@@ -104,6 +104,24 @@ agent = Agent(
 )
 ```
 
+### AIO Sandbox Mode
+
+```python
+from veadk import Agent
+
+agent = Agent(
+    model_name="doubao-seed-evolving",
+    skills_mode="aio_sandbox",
+    skills=["/workspace/skills"],
+)
+```
+
+Configure `VOLCENGINE_ACCESS_KEY`, `VOLCENGINE_SECRET_KEY`, `AGENTKIT_TOOL_ID` and model credentials, then create a Session and run the Agent through ADK/VeADK Runner. Construction never reads host Skill files. Before first execution, VeADK creates or reuses an AgentKit sandbox for the app/user/session identity; subsequent turns retain the same sandbox. Expired or failed sandboxes raise errors without automatic replacement or local fallback. Applications own instance lifecycle; idle instances expire by TTL.
+
+VeADK retains `SkillsToolset` and automatically supplies `skills_tool`, `bash_tool`, `read_file_tool`, `write_file_tool`, and `edit_file_tool`. Metadata comes from sandbox `GET /v1/skills`; instructions are read lazily through the remote file API. Commands and file operations execute inside the sandbox; relative paths use `/workspace`. Host environment variables are not forwarded to commands. Additional caller-supplied custom tools remain the caller's responsibility.
+
+`skills` accepts multiple absolute sandbox directories, sent as repeated `path` query parameters. Omitted or empty lists use the sandbox default `/workspace/skills`. Cloud SkillSpace IDs are not accepted here; existing AIO callers must migrate to sandbox paths. The sandbox must support `/v1/skills`, file APIs and Bash APIs. Optional `SANDBOX_API_KEY` authenticates sandbox HTTP requests; configured ADK `inbound_auth` credentials are reused. Bash timeout/cancellation attempts to kill remote commands and close temporary shells. Cleanup failures are reported; mutations are not retried automatically.
+
 ### Skill Checklist
 
 A skill can carry a checklist in its definition to constrain the Agent to complete the task step by step. When enabled, the Agent must complete each checklist item while executing the skill, and mark each item as done through the `update_check_list` tool:
@@ -137,7 +155,7 @@ agent = Agent(
 
 | Parameter | Type | Description |
 | :- | :- | :- |
-| `skills` | `list[str]` | Skill list; each item is a local skills root path or a cloud skill-space identifier. The legacy local loading path is deprecated when `skills_mode="local"`. |
-| `skills_mode` | `"local" \| "skills_sandbox" \| "aio_sandbox"` | Skill execution mode; inferred automatically when omitted. The legacy `local` path is deprecated, while `skills_sandbox` / `aio_sandbox` keep their existing behavior. |
+| `skills` | `list[str]` | Skill list; AIO items are absolute sandbox directories; other modes use local skills root paths or cloud skill-space identifiers. The legacy local loading path is deprecated when `skills_mode="local"`. |
+| `skills_mode` | `"local" \| "skills_sandbox" \| "aio_sandbox"` | Skill execution mode; inferred automatically when omitted. The legacy `local` path is deprecated, `skills_sandbox` retains its behavior, and `aio_sandbox` uses remote directories and basic tools. |
 | `enable_skills_checklist` | `bool` | Whether to enable the legacy skill checklist; defaults to `False`. |
 | `enable_dynamic_load_skills` | `bool` | Whether to enable dynamic loading for legacy skills; defaults to `False`. |
diff --git a/docs/content/docs/framework/agent/skills.mdx b/docs/content/docs/framework/agent/skills.mdx
@@ -2,7 +2,7 @@
 title: "技能"
 ---
 
-技能（Skills）是一种可复用的「提示词包」，用于为 Agent 注入特定的领域知识、操作流程与脚本。本地技能加载/执行场景推荐使用 Google ADK 官方的 `load_skill_from_dir` / `SkillToolset` 方式接入；VeADK 旧的 `Agent(skills=..., skills_mode="local")` 本地入口仍保持兼容，但已标记为 deprecated。`skills_sandbox` 与 `aio_sandbox` 模式仍按原方式使用。
+技能（Skills）是一种可复用的「提示词包」，用于为 Agent 注入特定的领域知识、操作流程与脚本。本地技能加载/执行场景推荐使用 Google ADK 官方的 `load_skill_from_dir` / `SkillToolset` 方式接入；VeADK 旧的 `Agent(skills=..., skills_mode="local")` 本地入口仍保持兼容，但已标记为 deprecated。`skills_sandbox` 通过云端技能空间执行；`aio_sandbox` 从绑定的沙箱加载技能并执行文件和 Shell 工具。
 
 ## 推荐：ADK SkillToolset
 
@@ -70,7 +70,7 @@ VeADK `skills` 参数仍支持三种技能运行模式，其中仅 `local` 的
 | :- | :- |
 | `local` | Deprecated。技能由 VeADK 旧 `skills_tool` 和配套文件/Shell 工具加载，建议迁移到 ADK `SkillToolset`。 |
 | `skills_sandbox` | 技能托管在云端技能空间（Skill Space），通过 `execute_skills` 工具在沙箱中执行。 |
-| `aio_sandbox` | All-in-one 沙箱模式，适用于 AgentKit 托管的工具运行时。 |
+| `aio_sandbox` | Runtime 执行推理，绑定的 All-in-one 沙箱提供 Skill 文件和基础工具；`skills` 为沙箱内绝对目录。 |
 
 未显式设置 `skills_mode` 时，VeADK 会根据运行环境自动推断：本地运行默认为 `local`；在 AgentKit 工具运行时中，会根据工具类型自动选择 `skills_sandbox` 或 `aio_sandbox`。
 
@@ -104,6 +104,24 @@ agent = Agent(
 )
 ```
 
+### AIO 沙箱模式
+
+```python
+from veadk import Agent
+
+agent = Agent(
+    model_name="doubao-seed-evolving",
+    skills_mode="aio_sandbox",
+    skills=["/workspace/skills"],
+)
+```
+
+配置 `VOLCENGINE_ACCESS_KEY`、`VOLCENGINE_SECRET_KEY`、`AGENTKIT_TOOL_ID` 和模型凭据后，通过 ADK/VeADK Runner 创建 Session 并运行 Agent。构造 Agent 不读取宿主机 Skill 文件；首次执行前按 app/user/session 身份创建或复用 AgentKit 沙箱，同一对话使用同一沙箱。沙箱过期或失败会报错，不自动更换实例或回退到本地。实例生命周期由应用管理，闲置实例按 TTL 过期。
+
+保留 VeADK `SkillsToolset`，自动提供 `skills_tool`、`bash_tool`、`read_file_tool`、`write_file_tool`、`edit_file_tool`。元数据通过沙箱 `GET /v1/skills` 获取，说明通过远端文件接口按需读取；命令和文件操作均在沙箱执行，相对路径基于 `/workspace`。宿主机环境变量不会传入命令环境；调用方额外传入的自定义工具仍由调用方负责。
+
+`skills` 可配置多个沙箱绝对目录，以重复 `path` 查询参数发送；省略或传空列表使用沙箱默认 `/workspace/skills`。这里不接受云端 SkillSpace ID；已有 AIO 调用方需要改为沙箱路径。沙箱需支持 `/v1/skills`、文件 API 和 Bash API。可选 `SANDBOX_API_KEY` 用于沙箱 HTTP 认证，ADK 配置的 `inbound_auth` 凭据沿用。Bash 超时/取消会尝试终止远端命令并关闭临时 Shell；清理失败会明确报告，写操作不自动重试。
+
 ### 技能检查清单（Checklist）
 
 技能可在其定义中携带一份检查清单（checklist），用于约束 Agent 按步骤完成任务。开启后，Agent 在执行技能时需逐项完成检查项，并通过 `update_check_list` 工具将每一项标记为已完成：
@@ -137,7 +155,7 @@ agent = Agent(
 
 | 参数 | 类型 | 说明 |
 | :- | :- | :- |
-| `skills` | `list[str]` | 技能列表，元素为本地技能根目录路径或云端技能空间标识；当 `skills_mode="local"` 时，该旧本地加载路径已 deprecated。 |
-| `skills_mode` | `"local" \| "skills_sandbox" \| "aio_sandbox"` | 技能运行模式，缺省时自动推断；其中 `local` 旧路径已 deprecated，`skills_sandbox` / `aio_sandbox` 仍保持原用法。 |
+| `skills` | `list[str]` | 技能列表；`aio_sandbox` 下为沙箱绝对目录，其他模式下为本地技能根目录路径或云端技能空间标识；当 `skills_mode="local"` 时，该旧本地加载路径已 deprecated。 |
+| `skills_mode` | `"local" \| "skills_sandbox" \| "aio_sandbox"` | 技能运行模式，缺省时自动推断；其中 `local` 旧路径已 deprecated，`skills_sandbox` 保持原用法，`aio_sandbox` 使用远端目录与基础工具。 |
 | `enable_skills_checklist` | `bool` | 是否启用旧技能检查清单，默认 `False`。 |
 | `enable_dynamic_load_skills` | `bool` | 是否启用旧技能的动态加载，默认 `False`。 |
diff --git a/prd-spec/features/aio-sandbox-skills/2026-10-26-aio-sandbox-skills.md b/prd-spec/features/aio-sandbox-skills/2026-10-26-aio-sandbox-skills.md
@@ -0,0 +1,48 @@
+# AIO sandbox skills and basic tools
+
+[中文版](2026-10-26-aio-sandbox-skills.zh.md)
+
+Change ID: `aio-sandbox-skills` · Date: 2026-10-26 · Status: implemented, with full-regression limitations below.
+
+## Background and scope
+
+VeADK's `aio_sandbox` branch previously returned no tools, while Skill initialization still resolved sources on the Runtime host. The goal is to retain `Agent(skills_mode="aio_sandbox", skills=[...])` and the existing `SkillsToolset`, with inference in Runtime and Skill files, commands and file operations in the sandbox. No new Agent field or execution-mode value is introduced. HTTP App/session APIs, Skill installation, other runtimes and additional discovery APIs are outside scope.
+
+## Requirements and design
+
+- **FR-1 — Entry point:** Mount `SkillsToolset` even with empty `skills`. In AIO mode, `skills` contains absolute sandbox directories; an empty list uses the sandbox's default directory. Construction must not read host Skill files or load cloud SkillSpace sources. `local` and `skills_sandbox` retain their behavior; AIO callers using SkillSpace IDs must migrate to sandbox directories.
+- **FR-2 — Session binding:** Before inference, create or reuse an AgentKit sandbox for the ADK app/user/session identity. Store only tool/session identifiers and the identity digest in ADK state. Subsequent turns reuse that sandbox; expired or non-Ready bindings fail without replacement or local fallback. The application owns instance lifecycle; idle instances expire by TTL.
+- **FR-3 — Skill loading:** Obtain names, descriptions and instruction-file paths through `GET /v1/skills`, passing repeated `path` parameters for multiple directories. Read instructions lazily through the sandbox file API. Tool descriptions and closures belong to the execution context; do not rewrite shared Agent instructions or share another Session's Skill catalog.
+- **FR-4 — Basic tools:** Route `skills_tool`, `bash_tool`, `read_file_tool`, `write_file_tool` and `edit_file_tool` to the same sandbox. Preserve existing tool names and model-visible arguments. Reads retain line numbering; edits require a unique match unless replacing all occurrences. Caller-supplied custom tools remain the caller's responsibility.
+- **FR-5 — Failures and isolation:** Never forward the host environment to commands. Preserve endpoint query parameters and existing authentication; keep credentials out of session state and diagnostics. Reject failed/malformed responses and redirects. Bash has a finite timeout, bounded output and remote kill/close on interruption; cleanup failures remain visible. Do not automatically retry mutations. Applications serialize concurrent turns of one ADK Session.
+
+Component-contract impact is limited to Agent Skill initialization and the AIO toolset branch described above; no Studio, model configuration or HTTP API contract changes. The implementation uses the existing lease resolver and a small data-plane helper, without monkey patching or a new backend hierarchy.
+
+## Tasks and acceptance
+
+| Requirement | Task | Acceptance criterion | Result |
+| --- | --- | --- | --- |
+| FR-1 | T-1: update Agent initialization and mode dispatch | AC-1: AIO mounts with empty skills and never loads host/cloud Skill sources | pass |
+| FR-2/3 | T-2: add session binding and remote discovery/loading | AC-2: isolated catalogs, multiple directories, lazy instruction reads and stable multi-turn binding | pass |
+| FR-4/5 | T-3: forward tools and handle failures/cleanup | AC-3: remote file roundtrip, edit semantics, timeout/cancellation, safe transport errors and no local fallback | pass |
+| FR-1–5 | T-4: run authorized live acceptance | AC-4: a new Session using `doubao-seed-evolving` calls bash and returns the configured `AGENTKIT_TOOL_ID`; host-only environment is absent; all five tools execute successfully | pass |
+
+Affected files: `veadk/agent.py`, `veadk/skills/check_skills_callback.py`, `veadk/tools/skills_tools/skills_toolset.py`, `veadk/tools/skills_tools/aio_sandbox.py`, `tests/skills/test_aio_sandbox_skills.py` and the paired Skills user documentation.
+
+## Review and verification
+
+The user approved the mode/toolset approach and authorized real model and sandbox acceptance. Direct review covered session isolation, compatibility, cancellation, cleanup and credential handling; no `review-spec` skill was available. The English/Chinese documents carry the same requirements and results. The user authorized commit, push and PR creation; no deployment is included.
+
+Verification date: 2026-10-26; scope: the working diff on `feat/newapi`, rebased onto `upstream/main` at `23014771`.
+
+| Check | Command or procedure | Outcome |
+| --- | --- | --- |
+| Related Python tests | `uv run --extra dev pytest tests/skills tests/tools/test_skills_bash_tool.py tests/tools/test_skills_session_path.py tests/agents -q` | pass: 153 tests |
+| Live acceptance | New ADK Session, `doubao-seed-evolving`, actual tool-call responses | pass: Tool ID matched; host environment isolated; file write/read/edit, Skill loading and sandbox reuse verified; temporary fixtures removed |
+| Lint, secrets and whitespace | `uv run --extra dev pre-commit run --all-files`; `git diff --check` | pass |
+| User documentation | `npm --prefix docs run types:check`; `npm --prefix docs run build` | pass |
+| Full regression | `uv run --extra dev pytest -n 2 -m "not codex_smoke and not piagent_smoke" --maxfail=3` | fail before rebasing (base `c662cc8d`): 3409 passed, 8 skipped, 6 failed before stopping; 3 migration-delivery tests require missing `zip`, and 3 Harness resource tests require missing `llama_index` |
+
+## Limits and risks
+
+The targeted and live acceptance passed; full-repository regression is not green. Missing executables/optional dependencies were not installed as part of this feature. A transport failure can leave a remote mutation's completion unknown, so such operations are not retried automatically. A sandbox must expose the Skill, file and Bash APIs used by the toolset. No new dependency or unrelated component change is included.