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
If you need to delegate a complete task to the remote sandbox rather than having the coordinator agent call individual tools, use the
AgentkitRemoteSandboxAgent sub-agent. See Remote sandbox sub-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 regionVEADK_RUN_CODE_ISOLATE_PARALLEL_CALLS: when multiplerun_codecalls execute in parallel within the same turn, whether each call gets a distinct sandbox session ID. Defaults totrue(enabled); set tofalseto have all parallel calls share the same session ID
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.CLOUD_PROVIDER=byteplus, BYTEPLUS_ACCESS_KEY, and BYTEPLUS_SECRET_KEY, plus BYTEPLUS_SESSION_TOKEN for STS. Volcengine STS uses VOLCENGINE_SESSION_TOKEN. The Tool ID, region, and endpoint must belong to the same environment. A basic AIO sandbox supplies execution facilities; execute_skills additionally requires a running skills A2A service, while coding and run_sandbox_agent require an executable agent.py workflow and dependencies in the target directory.
Start with the Python version check below to confirm connectivity before adding skills or business data.
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
When
SKILL_SPACE_POLICY is set, VeADK automatically forwards it to sandbox sessions created by execute_skills, invoke_skill, poll_skill, and run_sandbox_agent, so skill loading inside the sandbox follows the same filter as the local environment. No manual pass-through via extra_env_vars is needed. See SkillsSkill 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 that user identity is not forwarded; valid cloud credentials and permissions are still required to access the sandbox.
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
Parallel call isolation
When a synchronous tool thread pool is configured and the model issues multiplerun_code calls in the same turn, VeADK assigns each call a distinct sandbox session ID by appending its function-call identifier to the base session ID. This ensures that each run_code call runs in an isolated sandbox, with no interference between their file systems and runtime environments.
Without a thread pool configured, multiple
run_code calls in the same turn execute serially using the same base session ID and isolation does not apply.VEADK_RUN_CODE_ISOLATE_PARALLEL_CALLS environment variable:
Complete parameters for a selected sandbox workflow
run_sandbox_agent does not create or deploy agent.py; the sandbox must already contain that file and its dependencies.
coding accepts required workflow_prompt: str, injected tool_context=None, and timeout: int = 900. It runs a configured workflow through AGENTKIT_TOOL_ID_OPENCODE or the default Tool ID, rather than directly executing an arbitrary source-code string.
These tools return execution output, which can include remote errors or response objects. Check execution results, stderr, and expected artifacts before declaring completion. Waiting for a skill can end on required input, required authorization, or timeout without canceling the remote task.