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

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

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.

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 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
Last modified on September 19, 2026