代码沙箱

功能说明

VeADK 提供一组在 AgentKit 沙箱中远程执行任务的工具：

工具	说明
`run_code`	执行任意代码或 Shell 命令，适合计算、数据处理、依赖安装等
`execute_skills`	在预制技能沙箱中运行 `agent.py` 工作流
`coding`	在 OpenCode 沙箱中运行代码生成工作流
`run_sandbox_agent`	指定任意 `tool_id` 在远端沙箱执行 `agent.py`

导入路径：

from veadk.tools.builtin_tools.run_code import run_code
from veadk.tools.builtin_tools.execute_skills import execute_skills
from veadk.tools.builtin_tools.coding import coding
from veadk.tools.builtin_tools.run_sandbox_agent import run_sandbox_agent

环境变量与前提

附加要求：

配置火山引擎 AK / SK；
配置用于智能体推理模型的 API Key；
配置 AgentKit Tool ID（见下文）。

环境变量：

MODEL_AGENT_API_KEY：智能体推理模型的 API Key
VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY：火山引擎 AK / SK
AGENTKIT_TOOL_ID：默认 AgentKit 沙箱 ID，作为所有沙箱工具的兜底配置
AGENTKIT_TOOL_ID_SCRIPT：run_code 专用沙箱 ID，未配置时回退到 AGENTKIT_TOOL_ID
AGENTKIT_TOOL_ID_SKILLS：execute_skills 专用沙箱 ID，未配置时回退到 AGENTKIT_TOOL_ID
AGENTKIT_TOOL_ID_OPENCODE：coding 专用沙箱 ID，未配置时回退到 AGENTKIT_TOOL_ID
AGENTKIT_TOOL_HOST：调用 AgentKit Tools 的 Endpoint
AGENTKIT_TOOL_SERVICE_CODE：调用 AgentKit Tools 的 ServiceCode
AGENTKIT_TOOL_REGION：调用 AgentKit Tools 的地域，默认 cn-beijing
AGENTKIT_SKILL_INVOCATION_MODE：execute_skills 调用模式，未指定时默认 execute

config.yaml 配置项：

config.yaml

agentkit:
  tool_id: your-default-tool-id
  tool_id_script: your-script-tool-id
  tool_id_skills: your-skills-tool-id
  tool_id_opencode: your-opencode-tool-id

创建沙箱：

创建沙箱工具

在控制台创建沙箱工具：自定义名称（如 AIO_Sandbox_xxxx），工具集类型选择“一体化工具集”，包含 Browser、Terminal、Code 运行环境。

获取沙箱 ID

创建完成后，在控制台获取沙箱 ID（形如 t-ye8dj82xxxxx），填入上面的环境变量或 config.yaml。

使用方法

examples/tools/run_code/agent.py

import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.run_code import run_code
from veadk.tools.builtin_tools.web_search import web_search

agent = Agent(
    name="data_analysis_agent",
    model_name="doubao-seed-2-1-pro-260628",
    description="A data analysis agent for the stock market.",
    instruction=(
        "你是一名资深工程师，在沙箱中执行代码。可使用 web_search 搜索公司经营数据，"
        "可使用 akshare 等库下载股票数据；缺失依赖时用代码在沙箱中安装。"
    ),
    tools=[run_code, web_search],
)

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


async def main():
    response = await runner.run("分析阳光电源最近的股价走势")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

执行 Shell 命令

run_code 除了执行 Python 等代码外，还支持在沙箱中执行 Shell 命令。当 language 取值为 bash 或 shell 时，code 将作为 Shell 命令在远端沙箱中执行，适合文件操作、依赖安装、命令行工具调用等场景。执行 Shell 命令时复用 run_code 的沙箱 ID 与凭证配置，code 内容会作为命令提交，可在单次执行中串接多条命令。

Shell 可在远端沙箱中执行任意命令、安装依赖、读写文件，并访问沙箱网络可达的服务。运行前应确认命令来源可信，并限制沙箱可访问的数据、网络和权限；不要在命令或 env 中写入长期凭证，需要凭证时使用沙箱支持的凭据托管方式。

参数

run_code 的完整签名如下：

def run_code(
    code: str,
    language: str,
    tool_context: ToolContext,
    timeout: int = 30,
    exec_dir: str = "/tmp",
    env: dict[str, str] | None = None,
    hard_timeout: int = 300,
    max_output_length: int = 30000,
) -> str:
    ...

参数	类型	默认值	说明
`code`	`str`	—	要执行的代码或 Shell 命令。
`language`	`str`	—	执行语言。执行代码时取 `python3`；执行 Shell 命令时取 `bash` 或 `shell`。
`tool_context`	`ToolContext`	—	工具运行时上下文，由 VeADK 自动注入。
`timeout`	`int`	`30`	命令执行的超时时间，单位为秒。
`exec_dir`	`str`	`/tmp`	Shell 执行的工作目录。
`env`	`dict[str, str] \| None`	`None`	Shell 执行使用的环境变量。
`hard_timeout`	`int`	`300`	Shell 执行的硬超时时间，单位为秒。
`max_output_length`	`int`	`30000`	Shell 输出的最大长度。

exec_dir、env、hard_timeout 和 max_output_length 仅在执行 Shell 命令（language 为 bash 或 shell）时生效；执行代码时由沙箱运行时管理，不适用这些参数。

使用示例

run_code_bash.py

import asyncio

from google.adk.tools import ToolContext
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.run_code import run_code


def check_python(tool_context: ToolContext) -> str:
    """在远端沙箱中查看 Python 版本。"""
    return run_code(
        code="pwd && python --version",
        language="bash",
        tool_context=tool_context,
        timeout=60,
        exec_dir="/tmp",
        env={"APP_ENV": "test"},
        hard_timeout=120,
        max_output_length=5000,
    )


agent = Agent(
    name="shell_agent",
    instruction="调用工具查看远端沙箱的工作目录和 Python 版本。",
    tools=[check_python],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("检查沙箱环境")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

为沙箱执行注入环境变量

execute_skills 和 run_sandbox_agent 支持向本次沙箱执行注入自定义环境变量，用于向技能或沙箱内的工作流传入运行时参数（如配置项、凭证引用、特性开关等）。注入的环境变量仅在本次执行生效，不会持久化到沙箱基础环境。 execute_skills 通过 env_vars 参数注入；run_sandbox_agent 通过 extra_env_vars 参数注入。两者共享同一套校验与合并规则。

参数

参数	类型	默认值	说明
`env_vars`	`Optional[dict[str, str]]`	`None`	`execute_skills` 注入的环境变量，键值均为字符串，仅在本次执行生效。
`extra_env_vars`	`Optional[dict[str, str]]`	`None`	`run_sandbox_agent` 注入的环境变量，键值均为字符串，仅在本次执行生效。

校验规则

注入的环境变量会与 VeADK 框架自管理变量合并后传给沙箱进程，并按以下规则校验：

变量名必须匹配 ^[A-Za-z_][A-Za-z0-9_]*$，否则初始化会报错。
TOOL_USER_SESSION_ID 与 USER_SESSION_ID 由 VeADK 管理，不可通过自定义变量覆盖，否则初始化会报错。
变量值必须是字符串；非字符串值会报错。
变量值不能包含空字节（\x00），否则初始化会报错。
自定义变量会覆盖沙箱进程环境中的同名变量（包括 VeADK 默认设置的 TOS_SKILLS_DIR、SKILL_SPACE_ID 等），可用于按需调整本次执行的资源路径。

使用示例

下面的示例将两种调用封装为函数工具。Runner 调用函数工具时会注入 tool_context，应用只需在封装函数中设置本次执行需要的环境变量：

sandbox_env.py

import asyncio

from google.adk.tools import ToolContext
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.execute_skills import execute_skills
from veadk.tools.builtin_tools.run_sandbox_agent import run_sandbox_agent


def run_skill_workflow(workflow_prompt: str, tool_context: ToolContext) -> str:
    """在技能沙箱中运行工作流。"""
    return execute_skills(
        workflow_prompt=workflow_prompt,
        tool_context=tool_context,
        env_vars={
            "SKILL_CONFIG_PATH": "/tmp/skill_config.yaml",
            "MAX_RESULTS": "20",
        },
    )


def run_custom_workflow(workflow_prompt: str, tool_context: ToolContext) -> str:
    """在指定的 AgentKit 沙箱中运行工作流。"""
    return run_sandbox_agent(
        workflow_prompt=workflow_prompt,
        tool_id="t-your-sandbox-tool-id",
        tool_context=tool_context,
        extra_env_vars={"DATA_SOURCE_URL": "https://example.com/data.csv"},
    )


agent = Agent(
    name="sandbox_agent",
    instruction="根据用户要求调用合适的沙箱工作流。",
    skills=["space:your-skill-space-id"],
    skills_mode="skills_sandbox",
    tools=[run_skill_workflow, run_custom_workflow],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("使用技能工作流读取知识库并生成摘要")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

env_vars 和 extra_env_vars 的值会传入远端沙箱进程。不要在代码中写入长期凭证；需要凭证时，使用沙箱支持的凭据托管方式。

技能沙箱调用模式

execute_skills 支持通过 invocation_mode 参数选择技能沙箱的调用后端，适配不同版本的 Skill 沙箱镜像。也可以通过环境变量 AGENTKIT_SKILL_INVOCATION_MODE 全局设置；参数优先级高于环境变量。

调用模式	说明
`execute`	默认模式。通过 Skill HTTP API 的 `/v1/skills/execute` 接口同步执行技能工作流。
`run_sse`	通过 ADK Runtime 的 `/run_sse` 接口以 SSE 方式执行，适配只暴露 ADK Runtime 接口的 Skill 沙箱。
`a2a`	通过 A2A 协议的 `message/send` 方法同步等待执行结果，适配使用 A2A 协议的 Skill 沙箱。
`python_agent`	旧版 RunCode 路径，在沙箱内执行 `agent.py`。传入 `env_vars` 时始终使用此模式。
`skill_api`	`execute` 的别名，行为与 `execute` 一致。

传入 env_vars 参数时，无论 invocation_mode 取值如何，execute_skills 始终使用 python_agent 模式，因为自定义环境变量注入依赖进程级环境变量。

参数

参数	类型	默认值	说明
`invocation_mode`	`Optional[str]`	`None`	技能沙箱调用模式。未指定时读取 `AGENTKIT_SKILL_INVOCATION_MODE` 环境变量，均未设置时使用 `execute`。

使用示例

skill_invocation_mode.py

import asyncio

from google.adk.tools import ToolContext
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.execute_skills import execute_skills


def run_skill_workflow(workflow_prompt: str, tool_context: ToolContext) -> str:
    """在技能沙箱中运行工作流，使用 A2A 调用模式。"""
    return execute_skills(
        workflow_prompt=workflow_prompt,
        tool_context=tool_context,
        invocation_mode="a2a",
    )


agent = Agent(
    name="skill_agent",
    instruction="根据用户要求调用技能工作流。",
    skills=["space:your-skill-space-id"],
    skills_mode="skills_sandbox",
    tools=[run_skill_workflow],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("使用技能工作流读取知识库并生成摘要")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

功能说明

环境变量与前提

使用方法

执行 Shell 命令

参数

使用示例

为沙箱执行注入环境变量

参数

校验规则

使用示例

技能沙箱调用模式

参数

使用示例

​功能说明

​环境变量与前提

​使用方法

​执行 Shell 命令

​参数

​使用示例

​为沙箱执行注入环境变量

​参数

​校验规则

​使用示例

​技能沙箱调用模式

​参数

​使用示例

功能说明

环境变量与前提

使用方法

执行 Shell 命令

参数

使用示例

为沙箱执行注入环境变量

参数

校验规则

使用示例

技能沙箱调用模式

参数

使用示例