远端沙箱子智能体

功能说明

AgentkitRemoteSandboxAgent 是一个原生的 ADK 子智能体，将托管在 AgentKit 中的 Skill 或 CodeEnv 沙箱会话包装为一个独立的智能体。它可以作为应用的根智能体直接运行，也可以注册到 Agent 的 sub_agents 列表中，由协调智能体通过 transfer_to_agent 将任务委派给它。与代码沙箱工具的区别在于：沙箱工具（如 run_code、execute_skills）以独立工具的形式挂载到智能体上，由模型在推理过程中逐次调用；而 AgentkitRemoteSandboxAgent 作为一个完整的子智能体，接收一个文本任务并在远端沙箱中端到端执行，执行过程中的工具调用、流式进度和最终结果直接以事件形式返回，无需本地协调智能体逐工具编排。

AgentkitRemoteSandboxAgent 复用代码沙箱的基础设施与凭证配置。环境变量、Tool ID 等前提条件与代码沙箱页面中的说明一致，此处不再重复。

何时使用

适合以下场景：

需要将完整的编码、技能执行或文件操作任务委派给远端沙箱，而非拆分为多次工具调用；
需要一个能够接收任务转交并直接返回结果的子智能体，与协调智能体组成多智能体拓扑；
沙箱任务执行时间较长，希望以流式事件观察执行进度。

依赖与前提

使用前请确认：

配置火山引擎 AK / SK；
配置 AgentKit Tool ID；
远端沙箱镜像或技能服务满足协议要求。

导入路径：

from veadk import AgentkitRemoteSandboxAgent

AgentkitRemoteSandboxAgent 在构造时不发起网络请求；网络连接在首次运行时按需建立。

使用方法

作为子智能体

将 AgentkitRemoteSandboxAgent 注册到协调智能体的 sub_agents 列表中。协调智能体在推理过程中通过 transfer_to_agent 将任务委派给沙箱子智能体，后者在远端沙箱中执行任务并直接返回结果。

remote_sandbox_subagent.py

import os

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk import AgentkitRemoteSandboxAgent

sandbox = AgentkitRemoteSandboxAgent(
    name="sandbox",
    description="执行需要远端技能、Python、命令或文件操作的任务，并报告执行过程和结果。",
    tool_id=os.getenv("AGENTKIT_TOOL_ID"),
    tool_type=os.getenv("AGENTKIT_TOOL_TYPE") or None,
)

coordinator = Agent(
    name="coordinator",
    instruction=(
        "理解用户的请求。需要运行代码、操作文件或使用沙箱技能时，"
        "使用 transfer_to_agent 将任务交给 sandbox。"
        "sandbox 会直接展示工具过程并回答用户，无需重复总结。"
    ),
    sub_agents=[sandbox],
)

runner = Runner(agent=coordinator, short_term_memory=ShortTermMemory())

作为根智能体

也可以将 AgentkitRemoteSandboxAgent 直接作为应用的根智能体。此模式下没有本地协调智能体，用户发送的文本任务直接在远端沙箱中执行。

remote_sandbox_root.py

import os

from veadk import AgentkitRemoteSandboxAgent

root_agent = AgentkitRemoteSandboxAgent(
    name="remote_sandbox",
    description="执行远端技能、Python、命令或文件操作，并报告执行过程和结果。",
    tool_id=os.getenv("AGENTKIT_TOOL_ID"),
    tool_type=os.getenv("AGENTKIT_TOOL_TYPE") or None,
)

沙箱类型

AgentkitRemoteSandboxAgent 支持两种远端沙箱类型，由 tool_type 参数指定。未显式指定时，框架通过 AgentKit 控制面的 GetTool 接口自动发现。

类型	说明
`Skill`	通过 A2A 协议与技能沙箱交互，适用于托管在 AgentKit Skills Sandbox 中的技能工作流。
`CodeEnv`	通过 Codex Worker 协议与代码执行沙箱交互，适用于代码生成、命令执行和文件操作。CodeEnv 沙箱镜像需支持 Codex Worker 协议 v1 和 `tool_events` 能力。

私有工具必须显式指定 tool_type。自动发现仅适用于控制面返回 Skill 或 CodeEnv 类型的工具；对于兼容但类型不同的自定义工具，需显式指定匹配的类型。

参数

AgentkitRemoteSandboxAgent 继承自 BaseAgent，以下为构造参数：

参数	类型	默认值	说明
`name`	`str`	—	智能体名称，在应用内唯一。
`description`	`str`	—	智能体描述，供协调智能体判断何时转交任务。
`tool_id`	`str \| None`	`None`	AgentKit Tool ID。未指定时从 `AGENTKIT_TOOL_ID` 环境变量读取。
`tool_type`	`Literal["Skill", "CodeEnv"] \| None`	`None`	沙箱类型。未指定时自动发现。
`request_timeout`	`float`	`900`	单次任务执行的超时时间，单位为秒。取值范围为 0–86000。
`expiry_buffer`	`float`	`90`	会话租约过期缓冲时间，单位为秒。取值范围为 0–86400。
`ready_timeout`	`float`	`120`	等待沙箱会话就绪的超时时间，单位为秒。必须大于 0。
`ttl`	`int`	`1800`	沙箱会话的存活时间，单位为秒。取值范围为 60–86400。
`prefer_internal_endpoint`	`bool`	`False`	是否优先使用内部端点连接沙箱。
`endpoint`	`str \| None`	`None`	预置的会话端点地址，用于本地测试。指定时必须同时显式设置 `tool_type`，并跳过控制面会话管理。
`api_key`	`SecretStr \| None`	`None`	沙箱 API Key，用于数据面鉴权。设置后以 `X-API-Key` 请求头发送。

request_timeout + expiry_buffer + 2 * ready_timeout 必须小于 86400 秒，否则构造时会报错。
指定 endpoint 时必须同时显式设置 tool_type，否则构造时会报错。

环境变量

AgentkitRemoteSandboxAgent 使用以下环境变量，与代码沙箱共享同一套凭证和端点配置：

环境变量	默认值	说明
`AGENTKIT_TOOL_ID`	—	AgentKit Tool ID，作为沙箱会话的默认 Tool ID。
`AGENTKIT_TOOL_TYPE`	—	沙箱类型，取值为 `Skill` 或 `CodeEnv`。
`AGENTKIT_TOOL_REGION`	`cn-beijing`	AgentKit 控制面地域。
`AGENTKIT_TOOL_HOST`	—	AgentKit 控制面地址，用于覆盖默认端点。
`AGENTKIT_TOOL_SERVICE_CODE`	—	AgentKit 控制面 ServiceCode，用于指定 PPE / STG 等环境。
`AGENTKIT_TOOL_SCHEME`	—	AgentKit 控制面协议，取值为 `http` 或 `https`。
`VOLCENGINE_ACCESS_KEY`	—	火山引擎 AccessKey。
`VOLCENGINE_SECRET_KEY`	—	火山引擎 SecretKey。

会话管理

AgentkitRemoteSandboxAgent 在运行时自动管理远端沙箱会话：

按应用名称、用户标识和会话标识生成稳定的逻辑会话键，在沙箱侧创建或复用对应的物理会话；
会话使用 ttl 参数控制存活时间，到期后自动释放；
同一逻辑会话的并发调用会被串行化，避免同一会话上的重复执行；
会话就绪等待时间由 ready_timeout 控制，超时后报错。

沙箱会话的默认存活时间为 1800 秒（30 分钟），最长支持 86400 秒（24 小时）。会话在存活期内可复用，跨调用保持沙箱内的文件和运行环境状态。

入站身份凭证

当协调智能体的运行上下文中存在入站身份凭证时，AgentkitRemoteSandboxAgent 会以 inbound_auth 请求头将凭证转发给远端沙箱，使沙箱中的工作流能够以原始用户身份执行。当前请求未携带入站凭证时不附加该请求头，沙箱以匿名方式执行。

入站身份凭证的来源与配置方式参见入站认证。

安全边界

远端沙箱可以执行任意代码、命令和文件操作，并可访问沙箱网络可达的服务。运行前应确认沙箱来源可信，并限制沙箱可访问的数据、网络和权限。不要在任务指令或环境变量中写入长期凭证；需要凭证时使用沙箱支持的凭据托管方式。

错误处理

沙箱执行过程中发生的错误以事件形式返回，不会导致应用崩溃。常见错误情况包括：

沙箱会话未在就绪时间内变为可用状态；
任务执行超时；
沙箱镜像协议不兼容；
同一会话上已有正在执行的调用。

当任务因超时或取消而中断时，框架会尝试通知远端沙箱取消当前任务，避免无效执行。

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

功能说明

何时使用

依赖与前提

使用方法

作为子智能体

作为根智能体

沙箱类型

参数

环境变量

会话管理

入站身份凭证

安全边界

错误处理

​功能说明

​何时使用

​依赖与前提

​使用方法

​作为子智能体

​作为根智能体

​沙箱类型

​参数

​环境变量

​会话管理

​入站身份凭证

​安全边界

​错误处理

功能说明

何时使用

依赖与前提

使用方法

作为子智能体

作为根智能体

沙箱类型

参数

环境变量

会话管理

入站身份凭证

安全边界

错误处理