火山方舟
火山方舟
文档指南
请输入
- 文档首页
火山方舟调用工具调用联网搜索工具
复制全文
下载 pdf联网搜索工具
文档反馈
问问助手联网搜索工具可以为大模型获取实时的公开网络信息，适用于新闻、商品、天气、行业动态和事实核验等场景。您可以根据接口协议、搜索来源和搜索控制需求选择合适的工具。
支持的工具
联网搜索场景支持以下工具：
开通组件
无论您选择使用哪一种联网搜索工具，都必须先开通相应的组件。
- 登录方舟控制台，打开应用组件库 > 豆包搜索标签页。
- 在豆包搜索 Custom 版的操作列中点击开通服务。
- 登录方舟控制台，打开应用组件库 > 应用组件标签页。
- 在联网内容插件的操作列中点击开通服务。
示例代码
说明
注意
调用工具之前，请确认您已经按照本文说明开通相应的组件，否则调用时将会产生错误。
豆包搜索 Custom 版
请求示例：
返回示例：
联网内容插件
参数说明
Responses API（兼容 OpenAI Responses 接口协议）
通过 Responses API 调用豆包搜索 Custom 版时，工具类型仍为 web_search，并需要将 sources 显式设置为 ["doubao"]。doubao 不能与其他搜索来源同时配置。
- tools.type：固定为 web_search。
- tools.sources：固定传入 ["doubao"]。
- tools.limit：参数不生效，传入的值将被忽略。
- tools.max_keyword：参数不生效，传入的值将被忽略。
- tools.user_location：参数不生效，传入的值将被忽略。
- max_tool_calls：限制一次模型响应中可执行工具调用的最大轮次。
Messages API（兼容 Anthropic Messages 接口协议）
通过 Messages API 调用豆包搜索 Custom 版时，使用兼容 Anthropic Messages 接口协议的服务端工具配置：
- tools.name：工具名称。本文示例固定为 web_search。
- tools.type：工具类型或版本标识。本文示例使用 web_search_20250305。
- tools.max_uses：单个服务端工具在一次请求中的最大调用次数。
- tools.user_location：参数不生效，传入的值将被忽略。
- tools.allowed_domains：限制搜索结果仅来自允许访问的域名列表。
- tools.blocked_domains：限制搜索结果不包含禁止访问的域名列表。
Agent 场景下的用法
您可以在 Claude Code 或 Codex 中调用豆包搜索 Custom 版工具，该工具兼容 Anthropic Messages 接口协议和 OpenAI Responses API 接口协议。
Claude Code 通过兼容 Anthropic Messages 接口协议的服务调用豆包搜索能力。完成接入配置后，在 Claude Code 中对话时，如果模型判断您的问题需要通过搜索功能才能回答，那么模型会调用 Web Search 工具进行搜索。完整的配置和使用方法参见在 Claude Code 中使用 Web Search 工具。
注意
调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。
Codex 通过兼容 OpenAI Responses API 接口协议的服务调用豆包搜索能力。完成接入配置后，在 Codex 中对话时，如果模型判断您的问题需要通过搜索功能才能回答，那么模型会调用 Web Search 工具进行搜索。完整的配置和使用方法参见在 Codex 中使用 Web Search 工具。
注意
调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。
API 调用场景下的用法与配置
本节介绍联网搜索场景中的工具用法与常用配置。不同工具的差异以相关说明为准。
注意
本节内容仅适用于 Responses API，不适用于 Messages API。
开启流式调用
在 response 中设置 stream=True，即可开启流式调用，使响应以流式方式返回，从而更快地获取部分结果，同时可实时查看模型判断是否调用搜索的思考过程。
示例：
设置搜索来源
豆包搜索 Custom 版和联网内容插件的搜索来源配置方式不同：
- 豆包搜索 Custom 版：
- 通过 Responses API 调用时，工具类型仍为 web_search，并需要将 sources 显式设置为 ["doubao"]。doubao 不能与其他搜索来源同时配置。
- 通过 Messages API 调用时，使用的是兼容 Anthropic Messages 接口协议的服务端工具配置。本文示例中 tools.type 使用 web_search_20250305。
- 联网内容插件：默认通过 search_engine 搜索全网内容。您可以通过 tools.sources 添加以下内容源：
- "douyin"：抖音百科。
- "moji"：墨迹天气。
- "toutiao"：头条图文。
示例：
指定用户地理位置
您可以在 tools 中设置 user_location 字段，并提供用户的国家、地区和城市信息，以优化与地理位置相关的搜索结果。
示例：
设置搜索限制
说明
以下搜索限制参数仅联网内容插件支持，豆包搜索 Custom 版不支持。即当 sources 的值为 ["doubao"] 时，tools.limit、tools.max_keyword、tools.user_location 均不生效，向它们传入的值将被忽略。
- tools.max_keyword
- 作用：限制单轮搜索中可使用的最大关键词数量。
- 取值范围：1～50。
- 示例：如果模型原本计划搜索三个关键词（例如“大模型最新进展”、“2025 年科技创新”），但将 max_keyword 设置为 1，模型将仅使用第一个关键词进行搜索。关于 max_keyword 参数的具体使用方法和示例，请参见 创建模型响应。
- tools.limit
- 作用：限制单轮搜索操作返回的最大结果条数。
- 取值范围：1～50。
- 默认值：10。
- 说明：此参数会影响返回内容的规模和请求性能。单次搜索最多可返回 20 条结果，但单轮可能有多次搜索，默认召回 10 条。
- max_tool_calls
- 作用：限制在一次完整的模型响应中可以执行工具调用的最大轮次。
- 取值范围：1～10。
- 默认值：3。
示例：
查询搜索用量
您可以在 API 返回的参数中查看工具使用情况：
- usage.tool_usage：显示 Responses API 中工具的总调用次数。
- usage.tool_usage_details：显示 Responses API 中每个搜索源的详细调用次数，例如 search_engine、toutiao 或 doubao。
- Messages API：通过 usage.server_tool_use.web_search_requests 查看服务端工具发起的联网搜索请求次数。
设置系统提示词
系统提示词的设置对搜索请求的影响较大，建议进行优化以提升搜索的准确性与效率。以下两种系统提示词模板供您参考。
模板 1：
模板 2：
注意事项
- 自定义函数名称应避免使用 web_search，否则模型可能按内置工具优先级判断调用逻辑。
- doubao 只能单独配置，不能与 toutiao、douyin、moji 或 search_engine 等其他搜索来源同时使用。
- 豆包搜索 Custom 版支持 Responses API 和 Messages API；联网内容插件仅支持 Responses API。
- 联网内容插件是否触发搜索由模型判断。一轮搜索可能发起多个关键词搜索，可以通过 max_keyword 参数限制一轮搜索的关键词数量，以控制调用频次和成本。
- 豆包搜索 Custom 版和联网内容插件均不支持 caching 参数，该参数不可与 tools 参数一起使用，否则会返回 400 错误。
相关文档
- 计费
- 豆包搜索 Custom 版
- 普通 API 调用场景：豆包搜索产品计费
- Agent Plan 场景：套餐内 AFP 抵扣规则、超额后付费规则
- Coding Plan 场景：套餐概览
- 联网内容插件：按联网内容插件实际使用次数计费。具体收费标准详见联网内容插件产品计费。
- Agent 场景使用方法
- API 参考
-
- 错误码说明：错误码
最近更新时间：2026.10.14 15:16:41
这个页面对您有帮助吗？
有用
有用
无用
无用