Add create sandbox id define

[Sodawyx]

Thank you for creating a pull request to contribute to Serverless Devs agentrun-sdk-python code! Before you open the request please answer the following questions to help it be more easily integrated. Please check the boxes "[ ]" with "[x]" when done too.
Please select one of the PR types below to complete

---

Fix bugs

Bug detail

The specific manifestation of the bug or the associated issue.

Pull request tasks

• Add test cases for the changes
• Passed the CI test

---

Update docs

Reason for update

Why do you need to update your documentation?

Pull request tasks

• Update Chinese documentation
• Update English documentation

---

Add contributor

Contributed content

• Code
• Document

Content detail

if content_type == 'code' || content_type == 'document':
    please tell us `PR url`，like: https://github.com/Serverless-Devs/agentrun-sdk-python/pull/1
else:
    please describe your contribution in detail

---

Others

Reason for update

Why do you need to update your documentation?

[Copilot]

Pull request overview

This PR extends the Sandbox SDK APIs to support user-specified sandbox IDs during creation, fixes Config passthrough so request-level headers/tokens reach the Data API, and adjusts connect/connect_async to skip get_template when template_type is provided (avoiding AKSK-required control-plane calls). It also adds spec-driven OpenSpec documentation for these changes.

Changes:

• Add optional sandbox_id to Sandbox.create/create_async → SandboxClient.create_sandbox(_async) → SandboxDataAPI.create_sandbox(_async) and serialize it as sandboxId in the create request body.
• Fix config passthrough for get/stop/delete calls down to DataAPI HTTP methods, and change connect/connect_async to avoid get_template when template_type is provided.
• Add OpenSpec config and archived specs/tasks/design/proposals documenting the above behaviors.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
openspec/config.yaml	Adds OpenSpec rules/config for spec-driven workflow.
openspec/changes/archive/2026-03-05-remove-get-template-from-connect/*	Spec/proposal/design/tasks documenting connect skipping get_template when template_type is provided.
openspec/changes/archive/2026-03-05-fix-sandbox-config-passthrough/*	Spec/proposal/design/tasks documenting Config passthrough fixes.
openspec/changes/archive/2026-03-05-add-create-sandbox-id/*	Spec/proposal/design/tasks documenting optional sandboxId support on create.
agentrun/sandbox/sandbox.py	Adds sandbox_id to create overloads and changes connect logic to use provided template_type without calling get_template.
agentrun/sandbox/__sandbox_async_template.py	Template source for generated sandbox.py; adds sandbox_id plumbing and connect_async behavior change.
agentrun/sandbox/client.py	Adds sandbox_id to create methods; fixes config passthrough for get/stop/delete (sync+async).
agentrun/sandbox/__client_async_template.py	Template source for generated client.py; updates create signature and config passthrough calls.
agentrun/sandbox/api/sandbox_data.py	Adds sandbox_id serialization to create request body; forwards config into HTTP calls.
agentrun/sandbox/api/__sandbox_data_async_template.py	Template source for generated sandbox_data.py; adds sandboxId and config passthrough.

Comments suppressed due to low confidence (4)

agentrun/sandbox/sandbox.py:335

• Sandbox.create() accepts a config parameter but doesn't pass it into SandboxClient.create_sandbox(...), so per-call config (headers/token/timeouts) is ignored during sandbox creation. Please forward config to the client call (and keep template + generated file in sync).

        # 创建 Sandbox（返回基类实例）
        base_sandbox = cls.__get_client().create_sandbox(
            template_name=template_name,
            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
            sandbox_id=sandbox_id,
            nas_config=nas_config,
            oss_mount_config=oss_mount_config,
            polar_fs_config=polar_fs_config,
        )

agentrun/sandbox/__sandbox_async_template.py:327

• connect_async no longer validates that a provided template_type matches the server-side template type, but the Raises: docstring still claims it will error on mismatch. Please update the docstring to avoid promising a check that no longer exists (and keep generated sandbox.py in sync).

        """连接一个SandBox（异步）

        Args:
            sandbox_id: Sandbox ID
            template_type: 可选的类型参数，用于类型提示和运行时类型决定。
                提供时直接使用该类型决定返回的子类，不调用 get_template（无需 AKSK）。
                未提供时通过 get_template 获取类型（需要 AKSK）。
            config: 配置对象

        Returns:
            Sandbox: 根据模板类型返回对应的 Sandbox 子类对象

        Raises:
            ValueError: 如果模板类型不支持或与预期类型不匹配
        """

agentrun/sandbox/sandbox.py:260

• Sandbox.create_async() passes config into get_template_async, but does not pass config into SandboxClient.create_sandbox_async(...), so user-supplied headers/token are ignored for the actual sandbox creation request. Please forward config to the client call (and regenerate if this file is codegen output).

        # 创建 Sandbox（返回基类实例）
        base_sandbox = await cls.__get_client().create_sandbox_async(
            template_name=template_name,
            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
            sandbox_id=sandbox_id,
            nas_config=nas_config,
            oss_mount_config=oss_mount_config,
            polar_fs_config=polar_fs_config,
        )

agentrun/sandbox/__sandbox_async_template.py:190

• In the template source, Sandbox.create_async() does not pass the config parameter into SandboxClient.create_sandbox_async(...), so user-supplied config is ignored for the creation request. Please forward config to the client call so codegen output (sandbox.py) preserves per-request config.

        base_sandbox = await cls.__get_client().create_sandbox_async(
            template_name=template_name,
            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
            sandbox_id=sandbox_id,
            nas_config=nas_config,
            oss_mount_config=oss_mount_config,
            polar_fs_config=polar_fs_config,
        )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (2)

agentrun/sandbox/__sandbox_async_template.py:327

• connect_async 的 docstring 里 Raises: ValueError 仍描述“与预期类型不匹配”，但当前逻辑在用户传入 template_type 时已不再做类型校验（直接用传入值决定子类）。建议更新异常说明，避免误导使用者（例如仅说明不支持的类型、缺少 template_name 等场景）。

        """连接一个SandBox（异步）

        Args:
            sandbox_id: Sandbox ID
            template_type: 可选的类型参数，用于类型提示和运行时类型决定。
                提供时直接使用该类型决定返回的子类，不调用 get_template（无需 AKSK）。
                未提供时通过 get_template 获取类型（需要 AKSK）。
            config: 配置对象

        Returns:
            Sandbox: 根据模板类型返回对应的 Sandbox 子类对象

        Raises:
            ValueError: 如果模板类型不支持或与预期类型不匹配
        """

agentrun/sandbox/__sandbox_async_template.py:190

• Sandbox.create_async 接收了 config 参数并用于 get_template_async，但创建沙箱时调用 cls.__get_client().create_sandbox_async(...) 没有把 config 透传下去，导致用户传入的 headers/token 等配置不会进入 Data API 请求。建议在调用 create_sandbox_async 时显式传入 config=config，并通过 codegen 同步到生成文件。

        base_sandbox = await cls.__get_client().create_sandbox_async(
            template_name=template_name,
            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
            sandbox_id=sandbox_id,
            nas_config=nas_config,
            oss_mount_config=oss_mount_config,
            polar_fs_config=polar_fs_config,
        )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.