功能说明
VeADK 提供一组在 AgentKit 沙箱中远程执行任务的工具:
导入路径:
from veadk.tools.builtin_tools.run_code import run_codefrom veadk.tools.builtin_tools.execute_skills import execute_skillsfrom veadk.tools.builtin_tools.coding import codingfrom veadk.tools.builtin_tools.run_sandbox_agent import run_sandbox_agent
环境变量与前提
环境变量:MODEL_AGENT_API_KEY:智能体推理模型的 API KeyVOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY:火山引擎 AK / SKAGENTKIT_TOOL_ID:默认 AgentKit 沙箱 ID,作为所有沙箱工具的兜底配置AGENTKIT_TOOL_ID_SCRIPT:run_code专用沙箱 ID,未配置时回退到AGENTKIT_TOOL_IDAGENTKIT_TOOL_ID_SKILLS:execute_skills专用沙箱 ID,未配置时回退到AGENTKIT_TOOL_IDAGENTKIT_TOOL_ID_OPENCODE:coding专用沙箱 ID,未配置时回退到AGENTKIT_TOOL_IDAGENTKIT_TOOL_HOST:调用 AgentKit Tools 的 EndpointAGENTKIT_TOOL_SERVICE_CODE:调用 AgentKit Tools 的 ServiceCodeAGENTKIT_TOOL_REGION:调用 AgentKit Tools 的地域,默认cn-beijing
config.yaml 配置项:
config.yaml
1
创建沙箱工具
在控制台创建沙箱工具:自定义名称(如
AIO_Sandbox_xxxx),工具集类型选择“一体化工具集”,包含 Browser、Terminal、Code 运行环境。2
获取沙箱 ID
创建完成后,在控制台获取沙箱 ID(形如
t-ye8dj82xxxxx),填入上面的环境变量或 config.yaml。使用方法
examples/tools/run_code/agent.py
执行 Shell 命令
run_code 除了执行 Python 等代码外,还支持在沙箱中执行 Shell 命令。当 language 取值为 bash 或 shell 时,code 将作为 Shell 命令在远端沙箱中执行,适合文件操作、依赖安装、命令行工具调用等场景。
执行 Shell 命令时复用 run_code 的沙箱 ID 与凭证配置,code 内容会作为命令提交,可在单次执行中串接多条命令。
参数
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
技能沙箱执行
execute_skills 通过 A2A 协议在技能沙箱中执行工作流。调用时发送非阻塞的 message/send 请求,随后按指数递增的间隔轮询任务状态,直到任务达到终态或超时。支持的最长执行时间为 1800 秒(30 分钟)。
参数
execute_skills 的完整签名如下:
execute_skills 已移除 invocation_mode 参数和 AGENTKIT_SKILL_INVOCATION_MODE 环境变量,统一使用 A2A 协议执行。使用示例
execute_skills_timeout.py