跳转到主要内容
工具让智能体可以调用确定性的业务逻辑、外部服务或运行时能力。VeADK Go 同时支持 ADK Go 的函数工具、Toolset,以及 VeADK 提供的火山引擎内置工具。

最小函数工具

函数工具适合封装确定性的业务动作,例如计算、查询内部系统、读写业务对象。参数结构体上的 json 和 jsonschema tag 会帮助模型生成正确的 JSON 入参。
工具 handler 的第一个参数是 agent.Context。它可以读取 AppName()、AgentName()、UserID()、SessionID() 等运行上下文,适合把工具调用和业务请求串起来。

Web Search 与链接读取

Web Search 适合让智能体主动检索网页资料;Link Reader 适合在用户给出 URL 后读取页面、PDF 或视频链接的主要内容。
如果只需要读取指定网页,也可以使用 builtin_tools.NewWebFetchTool(...)。如果需要更强的网页抓取能力,可以查看 NewWebScraperTool(...)。

MCP Router Toolset

MCP Router 以 Toolset 形式接入。它适合把平台统一管理的一组工具暴露给智能体,而不是在应用代码里逐个实现工具。
可以用显式 MCP Router 地址:
也可以只提供 AgentKit MCP Toolset ID,让 VeADK Go 通过 AgentKit 解析 endpoint 和 API key:
MCP_TOOLSET_ID 也可以作为 MCP_ROUTER_ID 的别名。若同时配置了 url 或 api_key,显式配置会覆盖通过 ID 解析出的值。

Run Code 与 Skills Sandbox

NewRunCodeSandboxTool 会创建名为 run_code 的长耗时工具,把代码执行委托给 AgentKit Code Sandbox。
运行时需要提供 AgentKit 工具 ID。run_code 会优先读取脚本类工具 ID:
Skills Sandbox 适合把一个较完整的工作流交给远程 Skill 环境执行。同步等待结果时使用 execute_skills;需要非阻塞任务时使用 invoke_skill + poll_skill。
Skills Sandbox 通常需要:
如果智能体还需要读取远程 Skill 说明,可以配合 skilltool.NewReadOnlySkillToolset(...) 或 skilltool.NewSkillToolset(...),再放入 Toolsets。

常见工具类型

使用建议

  • 工具名称要稳定,描述要说明输入、输出和副作用。
  • 涉及写入、下单、审批等动作时,建议增加确认逻辑。
  • 外部工具凭证通过环境变量、Secret 或运行时状态传入,不写入文档仓或源码仓。
  • 长耗时工具应设置合理超时,并在 UI 或调用方展示执行中状态。
  • 对外部服务返回值做结构化错误处理,让模型能判断是否重试、换工具或向用户澄清。

有副作用工具的安全边界

当工具会修改外部系统、提交审批、发送消息、删除资源或产生费用时,不要只依赖模型自行判断。建议在业务层增加确认、权限和审计:
最后修改于 2026年10月20日