AgentKit Built-in Tools Quick Start Guide

Built-in Tools provide Agents with standardized sandbox runtime environments and tool interfaces. The all-in-one sandbox image integrates core capabilities including code execution, browser automation, and terminal operations, supporting standardized integration and API calls.

Core Capabilities

• Code Sandbox: Enables Agents to safely "run code"
• Browser Sandbox: Enables Agents to "interact with web pages like humans"
• Terminal Sandbox: Enables Agents to "operate the operating system console (Terminal) like humans"
• File System: Enables Agents to upload and download files

This document provides detailed instructions on how to integrate and use Built-in Tools in your Agent code, with a focus on the code execution sandbox functionality. By following this guide, you will learn how to create, configure, and invoke sandbox tools.

Prerequisites: Creating a Sandbox Tool

Before writing code, you need to create a sandbox tool instance in the Volcengine console:

1. Visit the AgentKit Built-in Tools Console
2. Create a new sandbox tool instance
3. Record the generated TOOL_ID for use in subsequent configuration

Agent Code Example

The following code demonstrates how to use VeADK to build an Agent with code execution capabilities. By integrating the Built-in Tools run_code tool, your Agent will be able to execute code safely within a sandbox environment.

We recommend using agentkit-cli to create a project from the Basic Agent template. After the template is created, you need to make the following modifications:

• Add the code execution tool run_code to your Agent
• Configure the environment variable AGENTKIT_TOOL_ID with your sandbox tool instance ID

Your final code file should look like this:

Complete Code

Save the code as simple_agent_tool.py:

from veadk import Agent, Runner
from veadk.tools.builtin_tools.run_code import run_code
from agentkit.apps import AgentkitSimpleApp

app = AgentkitSimpleApp()
agent: Agent = Agent(
    tools=[run_code],
)
runner = Runner(agent=agent)

@app.entrypoint
async def run(payload: dict, headers: dict) -> str:
    prompt = payload["prompt"]
    user_id = headers["user_id"]
    session_id = headers["session_id"]
    
    response = await runner.run(
        messages=prompt, 
        user_id=user_id, 
        session_id=session_id
    )
    return response

@app.ping
def ping() -> str:
    return "pong!"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

Code Explanation

• run_code Tool: Provides a secure code execution environment supporting multiple programming languages including Python and JavaScript
• session_id: Used to identify user sessions; requests with the same session_id will share the same sandbox instance
• Asynchronous Processing: Uses async/await syntax to support high-concurrency requests

Local Debugging

1. Install VeADK from Official Source

You can install veadk-python directly using the Python package manager pip from the PyPI platform:

pip install veadk-python

Note: The veadk-python version that supports calling built-in tools is 0.2.15 and above.

2. Configure Environment Variables

Before starting the Agent, you need to configure the following environment variables:

# Required: Sandbox tool ID (obtained from the console)
export AGENTKIT_TOOL_ID=t-ye7fhfmghsc1kdxxxxxx

# Required: Volcengine access credentials
export VOLCENGINE_ACCESS_KEY=your_ak
export VOLCENGINE_SECRET_KEY=your_sk

📝 Important Notes:

• Replace placeholders like your_ak, your_sk with your actual configuration values
• AGENTKIT_TOOL_ID is obtained after creating the sandbox tool in the Volcengine console

3. Start the Agent Service Locally

After configuring the environment variables, run the following command to start the Agent:

python simple_agent_tool.py

Once the service starts successfully, it will listen on http://0.0.0.0:8000, and you can invoke the Agent through this address.

4. Invoke the Agent

Tool Instance Invocation Mechanism

Tool instances support intelligent session-based scheduling management:

• Automatic Creation: When you first use a specific session_id to invoke, the system will automatically create the corresponding sandbox session instance
• Session Reuse: Multiple requests with the same session_id will share the same sandbox instance, maintaining continuity of code execution context
• Lifecycle: Each session instance has a default validity period of 30 minutes, after which it will be automatically destroyed
• Isolation: Requests with different session_id values use independent sandbox environments with no interference between them

Invocation Example

Use the following curl command to test the Agent's code execution capability:

curl --location 'http://localhost:8000/invoke' \
  --header 'Content-Type: application/json' \
  --header 'user_id: veadk-test' \
  --header 'session_id: local_session' \
  --data '{"prompt": "Give me a random prime number between 50 and 100"}'

Parameter Description:

• user_id: User identifier
• session_id: Session identifier, used to associate with the sandbox instance
• prompt: User's natural language request

Execution Log Example

After a successful invocation, the console will output detailed execution logs:

2025-11-23 21:10:24 | DEBUG | runner.py:578 - Function call: id='call_jwrcwdayjj8xnlgalyzzcoqq' args={'code': 'import random\n\ndef is_prime(n):\n    if n <= 1:\n        return False\n    if n == 2:\n        return True\n    if n % 2 == 0:\n        return False\n    for i in range(3, int(n**0.5) + 1, 2):\n        if n % i == 0:\n            return False\n    return True\n\nprimes_between = [p for p in range(50, 101) if is_prime(p)]\nrandom_prime = random.choice(primes_between)\nprint(random_prime)', 'language': 'python3'} name='run_code'
2025-11-23 21:10:24 | DEBUG | run_code.py:48 - tools endpoint: agentkit.cn-beijing.volces.com
2025-11-23 21:10:24 | DEBUG | run_code.py:54 - tool_user_session_id: veAgent_veadk-test_local_session
2025-11-23 21:10:24 | DEBUG | run_code.py:56 - Running code in language: python3, session_id=local_session, code=import random

def is_prime(n):
    if n <= 1:
        return False
    if n == 2:
        return True
    if n % 2 == 0:
        return False
    for i in range(3, int(n**0.5) + 1, 2):
        if n % i == 0:
            return False
    return True

primes_between = [p for p in range(50, 101) if is_prime(p)]
random_prime = random.choice(primes_between)
print(random_prime), tool_id=t-ye7yhff668o2eybtfvr0, host=agentkit.cn-beijing.volces.com, service=agentkit, region=cn-beijing
2025-11-23 21:10:24 | DEBUG | run_code.py:65 - Get AK/SK from tool context failed.
2025-11-23 21:10:24 | DEBUG | run_code.py:77 - Successfully get AK/SK from environment variables.
2025-11-23 21:10:25 | DEBUG | run_code.py:103 - Invoke run code response: {'ResponseMetadata': {'RequestId': '****', 'Action': 'InvokeTool', 'Version': '2025-10-30', 'Service': 'agentkit', 'Region': 'cn-beijing'}, 'Result': {'ToolId': 't-****', 'UserSessionId': '****', 'SessionId': 's-****', 'Endpoint': '', 'InternalEndpoint': '', 'Result': '{\n  "success": true,\n  "message": "Code executed successfully",\n  "data": {\n    "kernel_name": "python3",\n    "session_id": "****",\n    "status": "ok",\n    "execution_count": 1,\n    "outputs": [\n      {\n        "output_type": "stream",\n        "name": "stdout",\n        "text": "67\\n",\n        "data": null,\n        "metadata": {},\n        "execution_count": null,\n        "ename": null,\n        "evalue": null,\n        "traceback": null\n      }\n    ],\n    "code": "import random\\n\\ndef is_prime(n):\\n    if n \\u003c= 1:\\n        return False\\n    if n == 2:\\n        return True\\n    if n % 2 == 0:\\n        return False\\n    for i in range(3, int(n**0.5) + 1, 2):\\n        if n % i == 0:\\n            return False\\n    return True\\n\\nprimes_between = [p for p in range(50, 101) if is_prime(p)]\\nrandom_prime = random.choice(primes_between)\\nprint(random_prime)",\n    "msg_id": "****"\n  }\n}'}}
2025-11-23 21:10:38 | DEBUG | runner.py:586 - Event output: The random prime number between 50 and 100 is: 67
2025-11-23 21:10:38 | WARNING | runner.py:652 - No tracer is configured in the agent, no trace id provided.
INFO:     127.0.0.1:52785 - "POST /invoke HTTP/1.1" 200 OK

Deploying to Production

After completing local development and testing, you can deploy your Agent to the AgentKit platform:

1. Package Code: Ensure all dependencies are properly configured in requirements.txt
2. Platform Deployment: Refer to the Quick Start section in Runtime to deploy the tool. The main steps are:
   • Run the agentkit init command in the project root directory to initialize the project, which will generate the agentkit.yaml file (skip this step if already executed)
   • Ensure the agentkit.yaml file is configured with the application entry point set to your working application code simple_agent_tool.py:

     entry_point: simple_agent_tool.py

   • Ensure all dependencies are properly configured in requirements.txt
   • Follow the Quick Start guide and use the agentkit config and agentkit launch commands to configure and deploy the application
3. Invoke Application: After deployment, you can invoke the Agent through the API or SDK provided by the platform. Example invocation:

   agentkit invoke "Give me a random prime number between 50 and 100"