Overview
VeADK provides a set of tools that run tasks remotely in an AgentKit sandbox:
Import paths:
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
Environment & prerequisites
Environment variables:MODEL_AGENT_API_KEY: API key for the agent’s reasoning modelVOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY: Volcengine AK / SKAGENTKIT_TOOL_ID: default AgentKit sandbox ID, used as the fallback for all sandbox toolsAGENTKIT_TOOL_ID_SCRIPT: sandbox ID dedicated torun_code; falls back toAGENTKIT_TOOL_IDAGENTKIT_TOOL_ID_SKILLS: sandbox ID dedicated toexecute_skills; falls back toAGENTKIT_TOOL_IDAGENTKIT_TOOL_ID_OPENCODE: sandbox ID dedicated tocoding; falls back toAGENTKIT_TOOL_IDAGENTKIT_TOOL_HOST: endpoint for calling AgentKit ToolsAGENTKIT_TOOL_SERVICE_CODE: service code for calling AgentKit ToolsAGENTKIT_TOOL_REGION: region for calling AgentKit Tools. When unset,volcesmode falls back to theREGIONenvironment variable, then defaults tocn-beijing;byteplusmode does not readREGIONand uses the BytePlus default region
config.yaml keys:
config.yaml
1
Create a sandbox tool
Create a sandbox tool in the console: give it a name (e.g.
AIO_Sandbox_xxxx) and choose the “all-in-one tool set” type, which includes Browser, Terminal, and Code runtimes.2
Obtain the sandbox ID
After creation, obtain the sandbox ID from the console (looks like
t-ye8dj82xxxxx) and fill it into the environment variables or config.yaml above.Usage
examples/tools/run_code/agent.py
Running shell commands
In addition to running code such as Python,run_code can run shell commands in the sandbox. When language is set to bash or shell, the code is executed as a shell command in the remote sandbox — useful for file operations, installing dependencies, or invoking command-line tools.
Shell execution reuses the sandbox ID and credential configuration of run_code. The code is submitted as a command, so multiple commands can be chained within a single execution.
Parameters
The full signature ofrun_code:
exec_dir, env, hard_timeout, and max_output_length apply only when running shell commands (language set to bash or shell); they are managed by the sandbox runtime and do not apply when running code.
Example
run_code_bash.py
Injecting environment variables into sandbox executions
run_sandbox_agent accepts custom environment variables through the extra_env_vars parameter that are injected into a single sandbox execution. Use them to pass runtime parameters (configuration values, credential references, feature flags, and so on) to an in-sandbox workflow. Injected variables are scoped to the current execution only and are not persisted to the sandbox base environment.
execute_skills no longer supports injecting environment variables. Passing a non-None env_vars value raises an error.Parameters
Validation rules
Injected variables are merged with the framework-managed variables that VeADK sets itself, then passed to the sandbox process under these rules:- Names must match
^[A-Za-z_][A-Za-z0-9_]*$; otherwise initialization raises an error. TOOL_USER_SESSION_IDandUSER_SESSION_IDare managed by VeADK and cannot be overridden; initialization raises an error if they are set.- Values must be strings; non-string values raise an error.
- Values must not contain null bytes (
\x00); otherwise initialization raises an error. - Custom variables override any same-named variable in the sandbox process environment (including VeADK defaults such as
TOS_SKILLS_DIRandSKILL_SPACE_ID), so resource paths for a single execution can be adjusted on demand.
Examples
The following example wraps the call as a function tool.Runner injects tool_context when it invokes a function tool, while the application sets the environment variables for each execution in the wrapper:
sandbox_env.py
Skill sandbox execution
execute_skills runs a workflow in the skills sandbox through the A2A protocol. It sends a non-blocking message/send request and then polls the task status at exponentially increasing intervals until the task reaches a terminal state or the timeout expires. The maximum execution time is 1800 seconds (30 minutes).
Parameters
The full signature ofexecute_skills:
execute_skills has removed the invocation_mode parameter and the AGENTKIT_SKILL_INVOCATION_MODE environment variable. Execution now uses the A2A protocol exclusively.Example
execute_skills_timeout.py