内置工具使用指南¶

本文档旨在说明如何有效利用 veADK 内置工具（BuiltinTools）。这些工具提供了即用型功能（如网页搜索或代码执行器），赋予 Agent 通用能力。例如，需要从网络检索信息的 Agent 可直接使用 web_search 工具，无需额外配置。

使用方法¶

导入：从 veadk.tools.builtin_tools 模块导入所需工具。
配置：初始化工具并按需提供参数。
注册：将工具实例添加至 Agent 的 tools 列表。

from veadk import Agent
from veadk.tools.builtin_tools.web_search import websearch

# 在 Agent 初始化时注册工具
# Agent(tools=[websearch], other_params...)

工具注册后，Agent 会根据 用户提示 和指令自主决定是否调用。框架将在调用时自动执行工具。

重要提示：请务必查阅本文档末尾的“限制条件”部分。

工具列表¶

veADK 集成了以下火山引擎工具：

工具名称	功能说明	导入路径
`web_search`	通过融合信息搜索 API 进行全网搜索。	`from veadk.tools.builtin_tools.web_search import web_search`
`web_scraper`	聚合搜索（邀测），代码详见此处。	`from veadk.tools.builtin_tools.web_scraper import web_scraper`
`vesearch`	调用联网问答 Agent 进行搜索，支持头条搜索等。	`from veadk.tools.builtin_tools.vesearch import vesearch`
`image_generate`	根据文本描述生成图片。	`from veadk.tools.builtin_tools.image_generate import image_generate`
`image_edit`	编辑图片（图生图）。	`from veadk.tools.builtin_tools.image_edit import image_edit`
`video_generate`	根据文本描述生成视频。	`from veadk.tools.builtin_tools.video_generate import video_generate`
`run_code`	在 AgentKit 沙箱中执行代码。	`from veadk.tools.builtin_tools.run_code import run_code`
`lark`	集成飞书开放能力，实现文档处理、会话管理等。	`from veadk.tools.builtin_tools.lark import lark`
`las`	基于火山引擎 AI 多模态数据湖服务 LAS 进行数据管理。	`from veadk.tools.builtin_tools.las import las`
`mobile_run`	手机指令执行	`from veadk.tools.builtin_tools.mobile_run import create_mobile_use_tool`

公域搜索 (Web Search)¶

web_search 工具允许 Agent 通过融合信息搜索的 API 进行搜索。详情请参考融合信息搜索 API 文档。

使用 web_search 工具的附加要求

需要配置火山引擎 AK、SK 或者使用火山引 IAM 授权的临时 StsToken
需要配置用于 Agent 推理模型的API Key

代码环境变量

from veadk import Agent, Runner
from veadk.tools.builtin_tools.web_search import web_search
from veadk.memory.short_term_memory import ShortTermMemory


app_name = "veadk_app"
user_id = "veadk_user"
session_id = "veadk_session"

agent = Agent(
    name="WebSearchAgent",
    model_name="doubao-seed-1-6-250615",
    description="An agent that can get result from Web Search",
    instruction="You are a helpful assistant that can provide information use web search tool.",
    tools=[web_search],
)
short_term_memory = ShortTermMemory()

runner = Runner(
    agent=agent, short_term_memory=short_term_memory, app_name=app_name, user_id=user_id
)


async def main():
    response = await runner.run(
        messages="杭州今天的天气怎么样？", session_id=session_id
    )
    print(response)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

环境变量列表：

MODEL_AGENT_API_KEY：用于 Agent 推理模型 API Key
VOLCENGINE_ACCESS_KEY：用于调用WebSearch的火山引擎的AccessKey
VOLCENGINE_SECRET_KEY：用于调用WebSearch的火山引擎的SecretKey

或在 config.yaml 中定义：

config.yaml

model:
  agent:
    provider: openai
    name: doubao-seed-1-6-250615
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here
volcengine:
    # [optional] for Viking DB and `web_search` tool
  access_key: you-access-key-here
  secret_key: you-secret-key-here

运行结果：

运行结果

火山引擎搜索(VeSearch)¶

vesearch 工具允许Agent通过调用火山引擎的联网问答Agent来进行搜索，详情请参考联网问答 Agent。

使用 vesearch 工具的附加要求

需要配置火山引擎 AK、SK 或者使用火山引 IAM 授权的临时 StsToken
需要配置用于 Agent 推理模型的API Key
需要配置联网问答 Agent 的智能体ID，在控制台创建智能体后获取，控制台地址。配置项名称为：TOOL_VESEARCH_ENDPOINT。

代码环境变量

from veadk import Agent, Runner
from veadk.tools.builtin_tools.vesearch import vesearch
from veadk.memory.short_term_memory import ShortTermMemory


app_name = "veadk_app"
user_id = "veadk_user"
session_id = "veadk_session"
API_KEY = "vesearch_api_key"

agent = Agent(
    name="ve_search_agent",
    model_name="doubao-seed-1-6-250615",
    api_key=API_KEY,
    description="An agent that can get result from veSearch",
    instruction="You are a helpful assistant that can provide information use vesearch tool.",
    tools=[vesearch],
)
short_term_memory = ShortTermMemory()

runner = Runner(
    agent=agent, short_term_memory=short_term_memory, app_name=app_name, user_id=user_id
)


async def main():
    response = await runner.run(
        messages="杭州今天的天气怎么样？", session_id=session_id
    )
    print(response)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

环境变量列表：

MODEL_AGENT_API_KEY：用于 Agent 推理模型 API Key
VOLCENGINE_ACCESS_KEY：用于调用WebSearch的火山引擎的AccessKey
VOLCENGINE_SECRET_KEY：用于调用WebSearch的火山引擎的SecretKey
TOOL_VESEARCH_ENDPOINT：用于联网问答 Agent 的智能体ID。注：必须配置在环境变量里面

或在 config.yaml 中定义：

config.yaml

model:
  agent:
    provider: openai
    name: doubao-seed-1-6-250615
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here
volcengine:
    # [optional] for Viking DB and `web_search` tool
  access_key: you-access-key-here
  secret_key: you-secret-key-here

运行结果：

运行结果

代码执行(Run Code)¶

run_code 工具使代理能够执行代码。允许模型执行计算、数据处理或运行小程序等任务。

使用 run_code 工具的附加要求

需要配置火山引擎 AK、SK 或者使用火山引 IAM 授权的临时 StsToken
需要配置用于 Agent 推理模型的 API Key
需要配置 AgentKit Tools Id，详见：AgentKit 沙箱工具（Tools） 章节部分

代码环境变量

from veadk import Agent, Runner
from veadk.tools.builtin_tools.web_search import web_search
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.run_code import run_code

app_name = "veadk_app"
user_id = "veadk_user"
session_id = "veadk_session"

agent: Agent = Agent(
    name="data_analysis_agent",
    description="A data analysis for stock marketing",
    instruction="""
        你是一个资深软件工程师，在沙箱里执行生产的代码， 避免每次安装检查, 
        可以使用python lib akshare 下载相关的股票数据。可以通过web_search工具搜索相关公司的经营数据。如果缺失了依赖库, 
        通过python代码为沙箱安装缺失的依赖库。""",
    tools=[run_code, web_search],
)


short_term_memory = ShortTermMemory()

runner = Runner(
    agent=agent, short_term_memory=short_term_memory, app_name=app_name, user_id=user_id
)


async def main():
    response = await runner.run(messages="阳光电源？", session_id=session_id)
    print(response)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

以下是必须在环境变量里面的配置项：

AGENTKIT_TOOL_ID：用于调用火山引擎AgentKit Tools的沙箱环境Id
AGENTKIT_TOOL_HOST：用于调用火山引擎AgentKit Tools的EndPoint
AGENTKIT_TOOL_SERVICE_CODE：用于调用AgentKit Tools的ServiceCode

环境变量列表：

MODEL_AGENT_API_KEY：用于 Agent 推理模型 API Key
VOLCENGINE_ACCESS_KEY：用于调用WebSearch的火山引擎的AccessKey
VOLCENGINE_SECRET_KEY：用于调用WebSearch的火山引擎的SecretKey

或在 config.yaml 中定义：

config.yaml

model:
  agent:
    provider: openai
    name: doubao-seed-1-6-250615
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here
volcengine:
    # [optional] for Viking DB and `web_search` tool
  access_key: you-access-key-here
  secret_key: you-secret-key-here

运行结果：

运行结果

图像生成工具(Image Generate)¶

image_generate 该工具可以根据用户的描述生成图像

使用 image_generate 工具的附加要求

需要配置用于 Agent 推理模型的 API Key
需要配置用于 Agent 推理图像生成的模型名称

代码环境变量

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.generate_image import image_generate

app_name = "veadk_app"
user_id = "veadk_user"
session_id = "veadk_session"

agent = Agent(
    name="image_generate_agent",
    description=("根据需求生成图片."),
    instruction=(
        """
        你是一个图片生成专家，根据用户的需求生成图片。
        你可以使用的工具有：
            - image_generate
        你只能依靠自己和绘图工具来完成任务。
        """
    ),
    tools=[
        image_generate,
    ],
)

short_term_memory = ShortTermMemory()

runner = Runner(
    agent=agent, short_term_memory=short_term_memory, app_name=app_name, user_id=user_id
)


async def main():
    response = await runner.run(messages="生成一个可爱的小猫", session_id=session_id)
    print(response)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

环境变量列表：

MODEL_IMAGE_NAME：用于 Agent 推理图像生成的模型名称
MODEL_AGENT_API_KEY：用于 Agent 推理模型 API Key

或在 config.yaml 中定义：

config.yaml

model:
  agent:
    provider: openai
    name: doubao-seed-1-6-250615
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here
  image:
    name: doubao-seedream-4-0-250828
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here

运行结果：

运行结果

视频生成工具(Video Generate)¶

video_generate 该工具可以根据用户的描述生成图像

!!! warning "使用 video_generate 工具的附加要求": 1. 需要配置用于 Agent 推理模型的 API Key 2. 需要配置用于 Agent 推理视频生成的模型名称 3. 需要配置用于 Agent 推理图片生成的模型名称（该用例使用了 image_generate 工具，因此需要推理图像生成模型的配置）

代码环境变量

from veadk import Agent, Runner
from veadk.tools.builtin_tools.video_generate import video_generate
from veadk.tools.builtin_tools.image_generate import image_generate
from veadk.memory.short_term_memory import ShortTermMemory

app_name = "veadk_app"
user_id = "veadk_user"
session_id = "veadk_session"

agent = Agent(
    name="quick_video_create_agent",
    description=("You are an expert in creating images and video"),
    instruction="""You can create images and using the images to generate video, 
                 first you using the image_generate tool to create an image as the first_frame and next create the last_frame, 
                 then you using the generated first_frame and last_frame to invoke video_generate tool to create a video.
                 After the video is created, you need to return the full absolute path of the video avoid the user cannot find the video
                 and give a quick summary of the content of the video.
                """,
    tools=[image_generate, video_generate],
)


short_term_memory = ShortTermMemory()

runner = Runner(
    agent=agent, short_term_memory=short_term_memory, app_name=app_name, user_id=user_id
)


async def main():
    response = await runner.run(
        messages="首先生成一只小狗图片，然后生成一个小狗飞上天抓老鼠的图片，最终合成一个视频",
        session_id=session_id,
    )
    print(response)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

环境变量列表：

MODEL_VIDEO_NAME：用于 Agent 推理视频生成的模型名称
MODEL_IMAGE_NAME：用于 Agent 推理图像生成的模型名称
MODEL_AGENT_API_KEY：用于 Agent 推理模型 API Key

或在 config.yaml 中定义：

config.yaml

model:
  agent:
    provider: openai
    name: doubao-seed-1-6-250615
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here
  image:
    name: doubao-seedream-4-0-250828
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here
  image:
    name: doubao-seedance-1-0-pro-250528
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here

运行结果：

运行结果

飞书 MCP工具 (Lark MCP Tools)¶

lark 该MCP工具集可以帮助你快速实现 AI agent 与飞书开放能力的集成，实现基于 agent 的飞书云文档处理、会话管理、日历安排等自动化场景。

使用 lark 工具的附加要求（2、3、4获取方式详见：Lark创建应用 ）

需要配置用于 Agent 推理模型的 API Key
需要配置用于 Lark 服务的 Application ID
需要配置用于 Lark 服务的 API Key
需要配置用于 Lark 服务的 OAuthToken

代码环境变量

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.lark import lark_tools

app_name = "veadk_app"
user_id = "veadk_user"
session_id = "veadk_session"

agent = Agent(
    name="lark_agent",
    description=("飞书机器人"),
    instruction=(
        """
            你是一个飞书机器人，通过lark_tools给用户发消息。
        """
    ),
    tools=[
        lark_tools,
    ],
)

short_term_memory = ShortTermMemory()

runner = Runner(
    agent=agent, short_term_memory=short_term_memory, app_name=app_name, user_id=user_id
)


async def main():
    response = await runner.run(
        messages="给xiangya@bytedance.com发送'你好，我是lark agent'",
        session_id=session_id,
    )
    print(response)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

必须配置在环境变量的配置项：

TOOL_LARK_ENDPOINT：用于 Agent 推理视频生成的模型名称
TOOL_LARK_API_KEY：用于 Agent 推理图像生成的模型名称
TOOL_LARK_TOKEN：用于 Agent 推理模型 API Key

环境变量列表： - MODEL_AGENT_API_KEY：用于 Agent 推理模型 API Key

或在 config.yaml 中定义：

config.yaml

model:
  agent:
    provider: openai
    name: doubao-seed-1-6-250615
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here

运行结果：

运行结果

LAS MCP工具 (LAS MCP Tools)¶

LAS 该MCP工具集基于AI多模态数据湖服务LAS，提供多模态数据集的创建、预览、查询分析、编辑和清洗加工能力。

使用 las 工具的附加要求

需要配置用于 Agent 推理模型的 API Key
需要预先创建LAS通用数据集，并获得数据集的LAS DatasetId
需要配置用于 Las 服务的 DatasetId
需要配置用于 Las 服务的 URL，URL获取方式

代码环境变量

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.las import las

app_name = "veadk_app"
user_id = "veadk_user"
session_id = "veadk_session"

agent = Agent(
    name="las_agent",
    description=("use data from las"),
    instruction=(
        """
        你是一个诗人，根据用户的需求生成诗词。
        你可以使用的MCP工具集有：
            - las
        第一步你需要使用las工具去ds_public数据集检索相关内容，然后基于检索内容作为基础来写一首诗词。
        """
    ),
    tools=[
        las,
    ],
)

short_term_memory = ShortTermMemory()

runner = Runner(
    agent=agent, short_term_memory=short_term_memory, app_name=app_name, user_id=user_id
)


async def main():
    response = await runner.run(
        messages="写一首国风和木头、爱情相关的诗词", session_id=session_id
    )
    print(response)


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

必须配置在环境变量的配置项：

TOOL_LAS_URL：用于提供 LAS MCP Server 服务的地址
TOOL_LAS_DATASET_ID：配置使用LAS服务的数据集ID

环境变量列表： - MODEL_AGENT_API_KEY：用于 Agent 推理模型 API Key

或在 config.yaml 中定义：

config.yaml

model:
  agent:
    provider: openai
    name: doubao-seed-1-6-250615
    api_base: https://ark.cn-beijing.volces.com/api/v3/
    api_key: your-api-key-here

运行结果：

运行结果

手机指令执行 (Mobile Run)¶

mobile_run 该工具可以让Agent在云手机上完成手机任务。

使用 mobile_run 工具的附加要求

需要在火山购买云手机服务，并订购pod
根据自己的需要在云手机上配置环境，必须下载app，登录账号等。

代码环境变量

必须配置在环境变量的配置项： - TOOL_MOBIL_USE_TOOL_ID：用于执行命令的云手机id

或在 config.yaml 中定义：

config.yaml

  tool:
    mobile_use:
      tool_id:
        - product_id-pod_id
        - product_id-pod_id

  volcengine:
    access_key: xxx
    secret_key: xxx

获取方式： 1. 登录火山，进入云手机产品控制界面

云手机产品控制界面实例管理界面 2. tool_id 格式为：product_id-pod_id

运行结果：

系统工具¶

load_knowledgebase：检索知识库工具，在你给 Agent 传入 knowledgebase 参数后，将会自动挂载该工具，Agent 将在运行时自主决定何时查询知识库；
load_memory：检索长期记忆工具，在你给 Agent 传入 long_term_memory 参数后，将会自动挂载该工具，Agent 将在运行时自主决定何时查询长期记忆。

其它¶

AgentKit 沙箱工具（Tools）¶

AgentKit 沙箱工具提供了多种智能体在执行任务中需要的运行环境工具，支持快速集成与便捷调用，同时veADK提供了更多内置工具。一体化工具集包含 Browser、Terminal、Code 运行环境，支持自动根据任务切换。

创建沙箱 按以下步骤操作：

创建沙箱工具：自定义沙箱名称"AIO_Sandbox_xxxx"，工具集类型选择"一体化工具集"，描述"Python代码沙箱"
获取结果：创建完成后在控制台获取‘AIO_Sandbox_xxxx’对应的沙箱ID：t-ye8dj82xxxxx