AgentKit

Appearance

AgentKit Built-in Tools 快速开始指南 ​

Built-in Tools为Agent提供标准化的沙箱运行环境和工具接口。提供的All-in-one sandbox镜像集成了代码执行、浏览器自动化、终端操作等核心能力，支持标准化集成与API调用。

核心能力 ​

  • 提供code sandbox能力，让Agent安全地“运行代码”
  • 提供browser sandbox能力：让Agent“像人一样操作网页”
  • 提供terminal sandbox能力：让Agent“像人一样操作操作系统控制台（Terminal）”
  • 提供文件系统能力：让Agent上传、下载文件

本文档将详细介绍如何在智能体代码中集成和使用 Built-in Tools，特别是代码执行沙箱功能。通过本指南，您将学会如何创建、配置和调用沙箱工具。

前置准备：创建沙箱工具 ​

在开始编写代码之前，您需要先在火山引擎控制台创建一个沙箱工具实例：

  1. 访问 AgentKit Built-in Tools 控制台
  2. 创建新的沙箱工具实例
  3. 记录生成的 TOOL_ID，后续配置中会用到

智能体代码示例 ​

以下代码展示了如何使用 VeADK 构建一个具备代码执行能力的智能体。通过集成 Built-in Tools 的 run_code 工具，您的智能体将能够在沙箱环境中安全地执行代码。 我们推荐您使用agentkit-cli，从Basic Agent模版来创建项目。在模版创建完成后，你需要做以下修改：

  • 为智能体添加代码执行工具 run_code
  • 配置环境变量 AGENTKIT_TOOL_ID 为您的沙箱工具实例 ID 最终，您的代码文件应该如下：

完整代码 ​

将代码保存为simple_agent_tool.py

python
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)

代码说明 ​

  • run_code 工具：提供安全的代码执行环境，支持 Python、JavaScript 等多种编程语言
  • session_id：用于标识用户会话，同一 session_id 的请求将共享沙箱实例
  • 异步处理：使用 async/await 语法支持高并发请求

本地调试 ​

1. 官方源安装VeADK ​

您可以直接使用 Python 包管理工具 pip 从 PyPI 平台 来安装 veadk-python：

bash
pip install veadk-python

说明：支持调用built-in-tools的veadk-python版本为0.2.15及以上。

1. 配置环境变量 ​

在启动智能体之前，需要配置以下环境变量：

bash
# 必需配置：沙箱工具 ID（从控制台获取）
export AGENTKIT_TOOL_ID=t-ye7fhfmghsc1kdxxxxxx

# 必需配置：火山引擎访问凭证
export VOLCENGINE_ACCESS_KEY=your_ak
export VOLCENGINE_SECRET_KEY=your_sk

📝 注意事项：

  • 请将 your_ak、your_sk 等占位符替换为您的实际配置值
  • AGENTKIT_TOOL_ID 从火山引擎控制台创建沙箱工具后获取

2. 本地启动智能体服务 ​

配置完环境变量后，运行以下命令启动智能体：

bash
python simple_agent_tool.py

服务启动成功后，将监听 http://0.0.0.0:8000，您可以通过该地址调用智能体。

3. 调用智能体 ​

工具实例调用机制 ​

工具实例支持基于会话的智能调度管理：

  • 自动创建：首次使用某个 session_id 调用时，系统会自动创建对应的沙箱会话实例
  • 会话复用：相同 session_id 的多次请求将共享同一个沙箱实例，保持代码执行的上下文连续性
  • 生命周期：每个会话实例默认有效期为 30 分钟，超时后自动销毁
  • 隔离性：不同 session_id 的请求使用独立的沙箱环境，互不干扰

调用示例 ​

使用以下 curl 命令测试智能体的代码执行能力：

bash
curl --location 'http://localhost:8000/invoke' \
  --header 'Content-Type: application/json' \
  --header 'user_id: veadk-test' \
  --header 'session_id: local_session' \
  --data '{"prompt": "给我在50和100之间一个随机的质数"}'

参数说明：

  • user_id：用户标识符
  • session_id：会话标识符，用于关联沙箱实例
  • prompt：用户的自然语言请求

执行日志示例 ​

调用成功后，控制台会输出详细的执行日志：

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: 在50到100之间的随机质数为：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

部署到生产环境 ​

完成本地开发和测试后，您可以将智能体部署到 AgentKit 平台：

  1. 打包代码：确保所有依赖都已正确配置在 requirements.txt 中
  2. 平台部署：参考Runtime 快速开始 部分部署tool，主要有以下几步：
    • 在项目根目录运行 agentkit init 命令，初始化项目，会生成 agentkit.yaml 文件（如果前面已执行，跳过此步）
    • 确保agentkit.yaml文件配置，应用入口设置为您刚才已经调通的应用代码simple_agent_tool.py，即：
    yaml
    entry_point: simple_agent_tool.py
    • 确保所有依赖都已正确配置在 requirements.txt 中
    • 根据[快速开始]指南，通过agentkit config和agentkit launch命令，配置和部署应用。
  3. 调用应用：部署完成后，您可以通过平台提供的 API 或 SDK 调用智能体。调用示例：
    bash
    agentkit invoke "给我在50和100之间一个随机的质数"

Released under the Apache-2.0 License.

Copyright © 2025 Volcengine