Skip to main content

功能说明

VeADK 提供一组在 AgentKit 沙箱中远程执行任务的工具: 导入路径:
  • 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
  • from veadk.tools.builtin_tools.invoke_skill import invoke_skill
  • from veadk.tools.builtin_tools.poll_skill import poll_skill
如果需要将完整的任务委派给远端沙箱,而非由协调智能体逐工具调用,可以使用 AgentkitRemoteSandboxAgent 子智能体。详见远端沙箱子智能体。

环境变量与前提

附加要求:
  1. 配置火山引擎 AK / SK;
  2. 配置用于智能体推理模型的 API Key;
  3. 配置 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 的地域。未设置时,火山引擎模式回退到 REGION 环境变量,仍为空时默认 cn-beijing;byteplus 模式不读取 REGION,使用 BytePlus 默认地域
  • VEADK_RUN_CODE_ISOLATE_PARALLEL_CALLS:当同一轮中存在多个 run_code 并行调用时,是否为每个调用分配独立的沙箱会话标识。默认为 true(开启);设为 false 时所有并行调用共享同一会话标识
config.yaml 配置项:
config.yaml
创建沙箱:
1

创建沙箱工具

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

获取沙箱 ID

创建完成后,在控制台获取沙箱 ID(形如 t-ye8dj82xxxxx),填入上面的环境变量或 config.yaml。
使用 BytePlus 时设置 CLOUD_PROVIDER=byteplus 与 BYTEPLUS_ACCESS_KEY、BYTEPLUS_SECRET_KEY,STS 场景同时配置 BYTEPLUS_SESSION_TOKEN;火山引擎 STS 使用 VOLCENGINE_SESSION_TOKEN。Tool ID、区域和服务端点必须属于同一环境。创建普通 AIO 沙箱只能提供基础执行环境,execute_skills 还要求技能 A2A 服务可用,coding 与 run_sandbox_agent 要求目标目录存在可执行的 agent.py 工作流及其依赖 首次验证可先运行下文的 Python 版本检查,确认沙箱可达后再添加技能或业务数据

使用方法

examples/tools/run_code/agent.py

执行 Shell 命令

run_code 除了执行 Python 等代码外,还支持在沙箱中执行 Shell 命令。当 language 取值为 bash 或 shell 时,code 将作为 Shell 命令在远端沙箱中执行,适合文件操作、依赖安装、命令行工具调用等场景。 执行 Shell 命令时复用 run_code 的沙箱 ID 与凭证配置,code 内容会作为命令提交,可在单次执行中串接多条命令。
Shell 可在远端沙箱中执行任意命令、安装依赖、读写文件,并访问沙箱网络可达的服务。运行前应确认命令来源可信,并限制沙箱可访问的数据、网络和权限;不要在命令或 env 中写入长期凭证,需要凭证时使用沙箱支持的凭据托管方式。

参数

run_code 的完整签名如下:
exec_dir、env、hard_timeout 和 max_output_length 仅在执行 Shell 命令(language 为 bash 或 shell)时生效;执行代码时由沙箱运行时管理,不适用这些参数。

使用示例

run_code_bash.py

为沙箱执行注入环境变量

run_sandbox_agent 支持通过 extra_env_vars 参数向本次沙箱执行注入自定义环境变量,用于向沙箱内的工作流传入运行时参数(如配置项、凭证引用、特性开关等)。注入的环境变量仅在本次执行生效,不会持久化到沙箱基础环境。
execute_skills 已不再支持注入环境变量。传入 env_vars 参数会报错。

参数

校验规则

注入的环境变量会与 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
extra_env_vars 的值会传入远端沙箱进程。不要在代码中写入长期凭证;需要凭证时,使用沙箱支持的凭据托管方式。
设置 SKILL_SPACE_POLICY 环境变量后,VeADK 会自动将其转发到 execute_skills、invoke_skill、poll_skill 和 run_sandbox_agent 创建的沙箱会话,使沙箱中的技能加载遵循与本地相同的筛选规则。无需通过 extra_env_vars 手动传递。详见技能

技能沙箱执行

execute_skills 通过 A2A 协议在技能沙箱中执行工作流。调用时发送非阻塞的 message/send 请求,随后按指数递增的间隔轮询任务状态,直到任务达到终态或超时。支持的最长执行时间为 1800 秒(30 分钟)。 调用 execute_skills 时,VeADK 会从凭证服务中读取当前请求的入站身份凭证(凭证键为 inbound_auth),并以 inbound_auth 请求头转发给技能沙箱,使沙箱中的工作流能够以原始用户身份执行。若当前请求未携带入站凭证,则不附加该请求头,不转发该用户身份;访问沙箱仍需有效的云服务凭证与权限。
入站身份凭证的来源与配置方式参见入站认证。

参数

execute_skills 的完整签名如下:
execute_skills 已移除 invocation_mode 参数和 AGENTKIT_SKILL_INVOCATION_MODE 环境变量,统一使用 A2A 协议执行。

使用示例

execute_skills_timeout.py

并行调用隔离

当配置了同步工具线程池且模型在同一轮中发起多个 run_code 调用时,VeADK 默认为每个调用分配独立的沙箱会话标识:在基础会话标识后附加该调用的函数调用标识,使各 run_code 调用在相互隔离的沙箱中并行执行,互不影响彼此的文件系统和运行环境。
未配置线程池时,同一轮中的多个 run_code 调用串行执行,均使用相同的基础会话标识,不触发隔离逻辑。
通过环境变量 VEADK_RUN_CODE_ISOLATE_PARALLEL_CALLS 可控制此行为:

指定沙箱工作流的完整参数

run_sandbox_agent 不会为用户创建或部署 agent.py;目标沙箱需预先包含该文件和依赖 coding 接收必填 workflow_prompt: str、运行时注入的 tool_context=None 与 timeout: int = 900,使用 AGENTKIT_TOOL_ID_OPENCODE 或默认 Tool ID 调用预配置工作流,不接受任意代码字符串作为程序直接执行 这些工具返回执行输出,不保证每次都返回单纯的成功文本;远端错误也可能以输出或响应对象返回。检查退出结果、标准错误与预期产物后再确认完成。技能等待在需要输入、需要授权或超时时可能结束,不能据此断言远端任务已取消
最后修改于 2026年9月22日