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_agentfrom veadk.tools.builtin_tools.invoke_skill import invoke_skillfrom veadk.tools.builtin_tools.poll_skill import poll_skill
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).
When execute_skills is called, VeADK reads the inbound identity credential from the credential service (credential key inbound_auth) and forwards it to the skills sandbox in the inbound_auth request header, so the sandbox workflow runs under the original user identity. If the current request carries no inbound credential, the header is omitted and the sandbox executes anonymously.
For the source and configuration of inbound identity credentials, see Inbound authentication.
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