Skip to main content

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_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
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

Requirements:
  1. Configure Volcengine AK / SK.
  2. Configure the API key for the agent’s reasoning model.
  3. Configure the AgentKit Tool ID (see below).
Environment variables:
  • MODEL_AGENT_API_KEY: API key for the agent’s reasoning model
  • VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY: Volcengine AK / SK
  • AGENTKIT_TOOL_ID: default AgentKit sandbox ID, used as the fallback for all sandbox tools
  • AGENTKIT_TOOL_ID_SCRIPT: sandbox ID dedicated to run_code; falls back to AGENTKIT_TOOL_ID
  • AGENTKIT_TOOL_ID_SKILLS: sandbox ID dedicated to execute_skills; falls back to AGENTKIT_TOOL_ID
  • AGENTKIT_TOOL_ID_OPENCODE: sandbox ID dedicated to coding; falls back to AGENTKIT_TOOL_ID
  • AGENTKIT_TOOL_HOST: endpoint for calling AgentKit Tools
  • AGENTKIT_TOOL_SERVICE_CODE: service code for calling AgentKit Tools
  • AGENTKIT_TOOL_REGION: region for calling AgentKit Tools. When unset, volces mode falls back to the REGION environment variable, then defaults to cn-beijing; byteplus mode does not read REGION and uses the BytePlus default region
  • VEADK_RUN_CODE_ISOLATE_PARALLEL_CALLS: when multiple run_code calls execute in parallel within the same turn, whether each call gets a distinct sandbox session ID. Defaults to true (enabled); set to false to have all parallel calls share the same session ID
config.yaml keys:
config.yaml
Creating a sandbox:
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.
For BytePlus, set 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.
Shell can execute arbitrary commands, install dependencies, read and write files, and reach services available from the remote sandbox network. Run only trusted commands and restrict the data, network, and permissions available to the sandbox. Do not put long-lived credentials in commands or env; use the sandbox’s supported credential-hosting mechanism when credentials are required.

Parameters

The full signature of run_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_ID and USER_SESSION_ID are 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_DIR and SKILL_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
Values in extra_env_vars are passed to the remote sandbox process. Do not put long-lived credentials in source code; use the sandbox’s supported credential-hosting mechanism when credentials are required.
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 Skills

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 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 of execute_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 multiple run_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.
Control this behavior with the 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.
Last modified on September 22, 2026