内置工具
内置工具是 VeADK 预先封装好的原生函数工具,开箱即用,让 Agent 获得网页搜索、代码执行、图像 / 视频生成等火山引擎能力,无需自己实现底层逻辑。
本页介绍原生函数工具。基于 MCP(Model Context Protocol)接入的工具(飞书 / Lark、LAS 数据湖、视频云 VOD、MCP Router、Supabase 等)请见内置 MCP 工具。
使用方法
导入工具
从 veadk.tools.builtin_tools 导入需要的工具。
注册到 Agent
把工具实例放进 Agent 的 tools 列表即可:
from veadk import Agent
from veadk.tools.builtin_tools.web_search import web_search
agent = Agent(tools=[web_search])注册后,Agent 会根据用户输入与指令自主决定是否调用工具,框架在调用时自动执行。
内置工具依赖火山引擎相关服务。使用前请开通对应服务,并完成 AK/SK、API Key 等鉴权配置(见每个工具的“环境变量”说明),详见配置。
工具一览
| 工具 | 功能 | 导入路径 |
|---|---|---|
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 |
link_reader | 读取并解析网页链接内容 | from veadk.tools.builtin_tools.link_reader import link_reader |
web_fetch | 直接抓取网页 / PDF 并抽取正文(纯 HTTP,工具自身无需凭证) | from veadk.tools.builtin_tools.web_fetch import web_fetch |
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 |
text_to_speech | 语音合成(TTS) | from veadk.tools.builtin_tools.tts import text_to_speech |
run_code | 在 AgentKit 沙箱中执行代码 | from veadk.tools.builtin_tools.run_code import run_code |
execute_skills | 在预制技能沙箱中远程执行 agent.py 工作流 | from veadk.tools.builtin_tools.execute_skills import execute_skills |
coding | 在预制 OpenCode 沙箱中执行代码生成工作流 | from veadk.tools.builtin_tools.coding import coding |
run_sandbox_agent | 指定任意 tool_id 在远端 AgentKit 沙箱执行 agent.py | from veadk.tools.builtin_tools.run_sandbox_agent import run_sandbox_agent |
create_mobile_use_tool | 在云手机上执行手机操作任务 | from veadk.tools.builtin_tools.mobile_run import create_mobile_use_tool |
模型与鉴权配置在多个工具间通用。本页只在第一个用到的工具处完整展示一次 config.yaml,后续工具仅列出新增的配置项。完整配置说明见配置。
网页搜索(web_search)
web_search 让 Agent 通过融合信息搜索 API 进行全网搜索。详见融合信息搜索 API 文档。
附加要求
- 配置火山引擎 AK / SK,或使用火山引擎 IAM 授权的临时 StsToken;
- 配置用于 Agent 推理模型的 API Key。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.web_search import web_search
agent = Agent(
name="web_search_agent",
model_name="doubao-seed-1-8-251228",
description="An agent that answers questions with web search.",
instruction="You are a helpful assistant. Use the web_search tool when you need fresh information.",
tools=[web_search],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run("杭州今天的天气怎么样?")
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API KeyVOLCENGINE_ACCESS_KEY:火山引擎 AccessKeyVOLCENGINE_SECRET_KEY:火山引擎 SecretKey
或在 config.yaml 中配置(本页后续工具复用此结构):
model:
agent:
provider: openai
name: doubao-seed-1-8-251228
api_base: https://ark.cn-beijing.volces.com/api/v3/
api_key: your-api-key-here
volcengine:
# 供 Viking DB 与 web_search 等工具使用
access_key: your-access-key-here
secret_key: your-secret-key-here
火山引擎搜索(vesearch)
vesearch 通过火山引擎的联网问答 Agent 进行搜索。该工具从环境变量读取自己的凭证,无需在 Agent 上传入 api_key。
附加要求
- 配置用于 Agent 推理模型的 API Key;
- 配置联网问答 Agent 的智能体 ID(在控制台创建智能体后获取),写入环境变量
TOOL_VESEARCH_ENDPOINT; - 配置联网问答 Agent 的 API Key,写入环境变量
TOOL_VESEARCH_API_KEY。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.vesearch import vesearch
agent = Agent(
name="vesearch_agent",
model_name="doubao-seed-1-8-251228",
description="An agent that answers questions with veSearch.",
instruction="You are a helpful assistant. Use the vesearch tool to look things up online.",
tools=[vesearch],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run("杭州今天的天气怎么样?")
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API KeyTOOL_VESEARCH_ENDPOINT:联网问答 Agent 的智能体 ID(必须配置在环境变量中)TOOL_VESEARCH_API_KEY:联网问答 Agent 的 API Key

网页读取(link_reader)
link_reader 接收一组 URL,读取并解析其网页内容,常与搜索工具搭配,让 Agent 先检索链接再深入阅读。它使用 MODEL_AGENT_API_KEY 进行鉴权。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.link_reader import link_reader
agent = Agent(
name="link_reader_agent",
model_name="doubao-seed-1-8-251228",
description="An agent that reads and summarizes web pages.",
instruction="Use the link_reader tool to read the given URLs, then summarize them.",
tools=[link_reader],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run(
"读取 https://www.volcengine.com/docs/85508/1650263 并总结要点"
)
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API Key
网页抓取(web_fetch)
web_fetch 对给定 URL 发起一次普通 HTTP GET 并抽取正文:HTML 转 Markdown 或纯文本,PDF 用 pypdf 抽取文字。它不执行 JavaScript——纯前端渲染或需要登录的页面可能抽取不全。与 link_reader 不同,该工具自身无需任何凭证(纯 HTTP 抓取),适合让 Agent 阅读用户给出的文章、文档或任意公开链接。
参数:
url:要抓取的http(s)链接;extract_mode:markdown(默认,保留标题 / 链接 / 列表)或text(纯文本);max_chars:抽取内容的最大字符数(默认50000)。
返回 {"url", "title", "content", "truncated"},失败时返回 {"error": ...}。
安全与限制
- SSRF 防护:解析域名后拦截私网 / 环回 / 链路本地 / 保留地址,并对每一跳重定向(含
<meta refresh>)重新校验,最多跟随 3 跳。 - 上限:HTML 下载上限 2MB、PDF 10MB;请求超时 30 秒;结果在进程内缓存 15 分钟。
- 不渲染 JavaScript;未做 socket 级 DNS pinning(仅“解析后校验”)。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.web_fetch import web_fetch
agent = Agent(
name="web_fetch_agent",
model_name="doubao-seed-1-8-251228",
description="An agent that reads web pages and PDFs.",
instruction="Use the web_fetch tool to fetch the given URL, then answer based on its content.",
tools=[web_fetch],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run(
"抓取 https://arxiv.org/pdf/1706.03762 并总结这篇论文的核心思想"
)
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API Key(web_fetch工具本身无需额外凭证)
图像生成(image_generate)
image_generate 根据文本描述生成图片。图生图编辑见下文的 image_edit。
附加要求
- 配置用于 Agent 推理模型的 API Key;
- 配置用于图像生成的模型名称(
MODEL_IMAGE_NAME)。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.image_generate import image_generate
agent = Agent(
name="image_generate_agent",
model_name="doubao-seed-1-8-251228",
description="根据需求生成图片。",
instruction="你是一个图片生成专家,根据用户的需求调用 image_generate 工具生成图片。",
tools=[image_generate],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run("生成一只可爱的小猫")
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API KeyMODEL_IMAGE_NAME:图像生成模型名称
新增的 config.yaml 配置项:
model:
image:
name: doubao-seedream-4-0-250828
api_base: https://ark.cn-beijing.volces.com/api/v3/
api_key: your-api-key-hereimage_generate 是规范导入名。from veadk.tools.builtin_tools.generate_image import image_generate 仍可用,但 generate_image 模块已废弃,请改用 image_generate。

图像编辑(image_edit)
image_edit 在给定原图的基础上按文本指令做图生图编辑(替换元素、改风格等)。Agent 会从用户输入中提取原图与编辑要求,无需你手动构造参数。它使用独立的编辑模型环境变量 MODEL_EDIT_NAME(注意:与 image_generate 的 MODEL_IMAGE_NAME 不同)。
附加要求
- 配置用于 Agent 推理模型的 API Key;
- 配置用于图像编辑的模型名称(
MODEL_EDIT_NAME)。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.image_edit import image_edit
agent = Agent(
name="image_edit_agent",
model_name="doubao-seed-1-8-251228",
description="按指令编辑图片。",
instruction="你是一个图片编辑专家,根据用户给定的原图与要求调用 image_edit 工具完成编辑。",
tools=[image_edit],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run(
"把这张图 https://example.com/cat.png 里的猫换成一只小狗"
)
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API KeyMODEL_EDIT_NAME:图像编辑模型名称
新增的 config.yaml 配置项:
model:
edit:
name: doubao-seededit-3-0-i2i-250628
api_base: https://ark.cn-beijing.volces.com/api/v3/
api_key: your-api-key-here视频生成(video_generate)
video_generate 根据文本描述生成视频。下面的示例先用 image_generate 生成首帧与尾帧,再合成视频。
附加要求
- 配置用于 Agent 推理模型的 API Key;
- 配置用于视频生成的模型名称(
MODEL_VIDEO_NAME); - 若使用首尾帧合成,还需配置图像生成模型名称(
MODEL_IMAGE_NAME)。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.image_generate import image_generate
from veadk.tools.builtin_tools.video_generate import video_generate
agent = Agent(
name="video_generate_agent",
model_name="doubao-seed-1-8-251228",
description="An expert in creating images and videos.",
instruction=(
"先用 image_generate 生成首帧和尾帧,再用 video_generate 合成视频,"
"最后返回视频的绝对路径并简述视频内容。"
),
tools=[image_generate, video_generate],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run("生成一只小狗,再生成它飞上天空的画面,最终合成一个视频")
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API KeyMODEL_VIDEO_NAME:视频生成模型名称MODEL_IMAGE_NAME:图像生成模型名称
新增的 config.yaml 配置项:
model:
video:
name: doubao-seedance-1-0-pro-250528
api_base: https://ark.cn-beijing.volces.com/api/v3/
api_key: your-api-key-here
语音合成(text_to_speech)
text_to_speech 将文本合成为语音,并把音频保存到本地。
附加要求
- 配置用于 Agent 推理模型的 API Key;
- 配置 VeSpeech 服务的 App ID 与 API Key。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.tts import text_to_speech
agent = Agent(
name="tts_agent",
model_name="doubao-seed-1-8-251228",
description="An agent that speaks text aloud.",
instruction="Use the text_to_speech tool to synthesize the user's text into speech.",
tools=[text_to_speech],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run("把这句话读出来:你好,欢迎使用 VeADK")
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API KeyTOOL_VESPEECH_APP_ID:VeSpeech 服务的 App IDTOOL_VESPEECH_API_KEY:VeSpeech 服务的 API KeyTOOL_VESPEECH_SPEAKER:音色,默认为zh_female_vv_uranus_bigttsTOOL_VESPEECH_AUDIO_OUTPUT_PATH:音频输出目录,默认为系统临时目录
代码沙箱
VeADK 提供一组在 AgentKit 沙箱中远程执行任务的工具:
| 工具 | 说明 |
|---|---|
run_code | 执行任意代码,适合计算、数据处理等 |
execute_skills | 在预制技能沙箱中运行 agent.py 工作流 |
coding | 在 OpenCode 沙箱中运行代码生成工作流 |
run_sandbox_agent | 指定任意 tool_id 在远端沙箱执行 agent.py |
附加要求
- 配置火山引擎 AK / SK;
- 配置用于 Agent 推理模型的 API Key;
- 配置 AgentKit Tool ID(见下文)。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.run_code import run_code
from veadk.tools.builtin_tools.web_search import web_search
agent = Agent(
name="data_analysis_agent",
model_name="doubao-seed-1-8-251228",
description="A data analysis agent for the stock market.",
instruction=(
"你是一名资深工程师,在沙箱中执行代码。可使用 web_search 搜索公司经营数据,"
"可使用 akshare 等库下载股票数据;缺失依赖时用代码在沙箱中安装。"
),
tools=[run_code, web_search],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run("分析阳光电源最近的股价走势")
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API KeyVOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY:火山引擎 AK / SKAGENTKIT_TOOL_ID:run_code使用的代码执行沙箱 ID,也是其他沙箱工具的 兜底配置AGENTKIT_TOOL_ID_SKILLS:execute_skills专用沙箱 ID,未配置时回退到AGENTKIT_TOOL_IDAGENTKIT_TOOL_ID_OPENCODE:coding专用沙箱 ID,未配置时回退到AGENTKIT_TOOL_IDAGENTKIT_TOOL_HOST:调用 AgentKit Tools 的 EndpointAGENTKIT_TOOL_SERVICE_CODE:调用 AgentKit Tools 的 ServiceCodeAGENTKIT_TOOL_REGION:调用 AgentKit Tools 的地域,默认cn-beijing
新增的 config.yaml 配置项:
agentkit:
tool_id: your-default-tool-id
tool_id_script: your-script-tool-id
tool_id_skills: your-skills-tool-id
tool_id_opencode: your-opencode-tool-id创建沙箱
- 在控制台创建沙箱工具:自定义名称(如
AIO_Sandbox_xxxx),工具集类型选择“一体化工具集”,包含 Browser、Terminal、Code 运行环境。

- 创建完成后,在控制台获取沙箱 ID(形如
t-ye8dj82xxxxx),填入上面的环境变量或config.yaml。


手机操作(mobile_run)
create_mobile_use_tool() 返回一个让 Agent 在云手机上完成操作任务的工具。
附加要求
- 在火山引擎购买云手机服务并订购 pod;
- 按需在云手机上配置环境(安装 App、登录账号等)。
import asyncio
from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.mobile_run import create_mobile_use_tool
agent = Agent(
name="mobile_agent",
model_name="doubao-seed-1-8-251228",
description="An agent that operates a cloud phone.",
instruction="Use the mobile tool to complete tasks on the cloud phone.",
tools=[create_mobile_use_tool()],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())
async def main():
response = await runner.run("打开购物 App 搜索“耳机”")
print(response)
if __name__ == "__main__":
asyncio.run(main())环境变量:
MODEL_AGENT_API_KEY:Agent 推理模型的 API KeyTOOL_MOBILE_USE_TOOL_ID:云手机实例 ID,格式为product_id-pod_idVOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY:火山引擎 AK / SK
tool_id 格式为 product_id-pod_id,在云手机控制台的实例管理界面获取。
