# 联网搜索工具
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
联网搜索工具可以为大模型获取实时的公开网络信息，适用于新闻、商品、天气、行业动态和事实核验等场景。您可以根据接口协议、搜索来源和搜索控制需求选择合适的工具。
---
## 支持的工具
联网搜索场景支持以下工具：
| 对比项 | 豆包搜索 Custom 版（推荐） | 联网内容插件 |
| --- | --- | --- |
| 支持的 API | Responses API（兼容 OpenAI Responses 接口协议）、Messages API（兼容 Anthropic Messages 接口协议） | Responses API（兼容 OpenAI Responses 接口协议） |
| 支持的模型 | 参见[工具调用能力](/docs/model-list#f44ceef7) | 参见[工具调用能力](/docs/model-list#f44ceef7) |
| 核心功能 | 支持多垂类、多信源的实时公开信息，搜索时延低、控制更灵活；支持与函数调用、MCP 等工具组合使用。 | 支持多轮自动搜索、图文输入和多工具混合调用；支持同步和流式响应。 |
| 计费说明 | * Agent Plan 场景：参见[套餐内 AFP 抵扣规则](/docs/agent-plan-personal-afp-credits-billing-rules)、[超额后付费规则](/docs/agent-plan-personal-over-quota-postpaid-rules)。 | 按联网内容插件实际使用次数计费。具体收费标准详见[联网内容插件产品计费](/docs/online-content-plugin-pricing)。 | \
| | * Coding Plan 场景：参见[套餐概览](/docs/coding-plan-personal-plan-overview)。 | | \
| | * 普通 API 调用场景：参见 [豆包搜索产品计费](https://docs.volcengine.com/docs/87772/2272951?lang=zh#yQ0Kqmsy)。 | |
## 开通组件
无论您选择使用哪一种联网搜索工具，都必须先开通相应的组件。
**选项：豆包搜索 Custom 版**
1. 登录方舟控制台，打开 [应用组件库 > 豆包搜索](https://ark.volcengine.com/region:cn-beijing/openManagement?advancedActiveKey=component&tab=DoubaoSearch) 标签页。
2. 在**豆包搜索 Custom 版**的**操作**列中点击**开通服务**。
**选项：联网内容插件**
1. 登录方舟控制台，打开 [应用组件库 > 应用组件](https://ark.volcengine.com/region:cn-beijing/openManagement?advancedActiveKey=component&tab=DoubaoSearch) 标签页。
2. 在**联网内容插件**的**操作**列中点击**开通服务**。
## 示例代码
> **说明**
>
> 方舟平台的新用户？获取 API Key 及 开通模型等准备工作，请参见 [快速入门](/docs/quick-start)。
> **注意**
>
> 调用工具之前，请确认您已经按照本文说明开通相应的组件，否则调用时将会产生错误。
### 豆包搜索 Custom 版
请求示例：
**选项：Responses API（OpenAI Responses 协议）**
```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer $ARK_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "doubao-seed-2-1-pro-260915",
"stream": true,
"tools": [
{
"type": "web_search",
"sources": ["doubao"]
}
],
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "今天有什么 AI 领域的热点新闻？"
}
]
}
]
}'
```
**选项：Messages API（Anthropic Messages 协议）**
```Bash
curl https://ark.cn-beijing.volces.com/api/compatible/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: $ARK_API_KEY" \
-d '{
"model": "doubao-seed-2-1-pro-260915",
"max_tokens": 1024,
"tools": [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}
],
"messages": [
{
"role": "user",
"content": "今天有什么 AI 领域的热点新闻？"
}
]
}'
```
返回示例：
**选项：Responses API**
```
{
"id": "resp_02178849073345588e74****",
"object": "response",
"model": "doubao-seed-2-1-pro-260915",
"status": "completed",
"output": [
{
"id": "rs_02178849073770400000****",
"type": "reasoning",
"status": "completed",
"summary": [
{
"type": "summary_text",
"text": "用户需要获取 2026 年 9 月 4 日的 AI 领域热点新闻，我将使用网页搜索工具，通过时间限定关键词检索相关信息。"
}
],
"encrypted_content": "djFlkf4Bo9PjH2A5r+39.../9yJWTg="
},
{
"id": "ws_02178849074154500000****",
"type": "web_search_call",
"status": "completed",
"action": {
"type": "search",
"query": "2026年9月4日 AI领域热点新闻",
"queries": [
"2026年9月4日 AI领域热点新闻"
]
}
},
{
"id": "msg_02178849076046900000****",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "2026年9月4日 AI 领域的核心热点是 OpenAI 正式发布新一代旗舰大模型 GPT-6 Astra。",
"annotations": [
{
"type": "url_citation",
"title": "OpenAI，发布“地球最强大模型”GPT-6：欢迎进入 AGI 时代！",
"url": "https://news.sina.cn/2026-09-04/detail-iniqrpra63******.d.html",
"site_name": "新浪新闻",
"publish_time": "2026-09-04T10:24:00+08:00",
"summary": "当地时间 9 月 3 日，OpenAI 正式发布新一代旗舰模型 GPT-6 Astra，并称其实现“代际跃迁”。"
}
]
}
]
}
],
"usage": {
"input_tokens": 3666,
"output_tokens": 1610,
"total_tokens": 5276,
"tool_usage": {
"web_search": 1
},
"tool_usage_details": {
"web_search": {
"doubao": 1
}
}
}
}
```
**选项：Messages API**
```JSON
{
"id": "021788491735391ee3582c20fb7529745750c3f00520e5c262****",
"type": "message",
"role": "assistant",
"model": "doubao-seed-2-1-pro-260915",
"content": [
{
"type": "thinking",
"thinking": "我将调用搜索工具获取 2026 年 9 月 4 日的 AI 热点新闻，再基于搜索结果整理回答。",
"signature": "djE09ahKIu8KsvSLLVrg...Nf/EYMTk3hjlMg=="
},
{
"type": "server_tool_use",
"id": "srvtoolu_2ccc8b83a8d345f8be35d32b457e****",
"name": "web_search",
"input": {
"query": "2026年9月4日 AI领域热点新闻"
}
},
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_2ccc8b83a8d345f8be35d32b457e****",
"content": [
{
"type": "web_search_result",
"title": "OpenAI，发布“地球最强大模型”GPT-6：欢迎进入AGI时代！山姆·奥特曼首次明确表示：一定会做人形机器人",
"url": "https://news.sina.cn/2026-09-04/detail-iniqrpra63****.d.html",
"page_age": "2026-09-04T10:24:00+08:00",
"encrypted_content": "djGk3VaymgA8eiuLkR7w...0QazEoRxp46hi3n/Zd5L2aG3kN7cexLZzcoSdoA6f34iEEJBw=="
},
{
"type": "web_search_result",
"title": "OpenAI最强模型GPT-6 Astra发布，公司总裁称AGI时代到来",
"url": "http://finance.sina.cn/stock/jdts/2026-09-04/detail-iniqrpqy08****.html",
"page_age": "2026-09-04T10:25:00+08:00",
"encrypted_content": "djEz4PKCbjpmdizu9giy...p4I8TYtvYardgTA9CgOtejh6rWWpAFvj29xL+I/mK1vAOPs0tm+4NU=="
}
]
},
{
"type": "text",
"text": "根据 2026 年 9 月 4 日的 AI 领域最新热点，最重磅的事件是 OpenAI 正式发布新一代旗舰大模型 GPT-6 Astra。"
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 3770,
"output_tokens": 1859,
"cache_read_input_tokens": 0,
"server_tool_use": {
"web_search_requests": 1,
"web_fetch_requests": 0
}
}
}
```
### 联网内容插件
**选项：cURL**
```Bash
curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \
--header "Authorization: Bearer $ARK_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "doubao-seed-2-1-pro-260915",
"stream": true,
"tools": [
{
"type": "web_search",
"max_keyword": 2
}
],
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "今天有什么热点新闻？"
}
]
}
]
}'
```
**选项：Python SDK**
```Python
import os
from arkruntime import Ark
# To obtain the api key from your environment variables, see: https://ark.volcengine.com/region:cn-beijing/docs/environment-variable-configuration-guide
api_key = os.getenv('ARK_API_KEY')
client = Ark(
base_url='https://ark.cn-beijing.volces.com/api/v3',
api_key=api_key,
)
tools = [{
"type": "web_search",
"max_keyword": 2,
}]
# Create a conversation request
response = client.responses.create(
model="doubao-seed-2-1-pro-260915",
input=[{"role": "user", "content": "今天有什么热点新闻？"}],
tools=tools,
)
print(response)
```
**选项：Java SDK**
```Java
package com.ark.example;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import com.volcengine.ark.runtime.models.responses.*;
import com.volcengine.ark.runtime.service.ArkService;
import java.util.Arrays;
import java.util.List;
public class demo {
public static ObjectMapper om = new ObjectMapper();
public demo() throws JsonProcessingException {
}
public static List buildTools() {
WebSearchTool t = WebSearchTool.builder()
.build();
System.out.println(Arrays.asList(t));
return Arrays.asList(t);
}
public static void main(String[] args) throws JsonProcessingException {
String apiKey = System.getenv("ARK_API_KEY");
// Create an ArkService instance
ArkService arkService = ArkService.builder().apiKey(apiKey)
.baseUrl("https://ark.cn-beijing.volces.com/api/v3")
.build();
ResponsesRequest req = ResponsesRequest.builder()
.model("doubao-seed-2-1-pro-260915")
.input(ResponsesInput.ofList(java.util.Arrays.asList(ItemEasyMessage.builder().role(MessageRole.USER).content(
MessageContent.ofList(java.util.Arrays.asList(ContentItemText.builder().text("今天有什么热点新闻？").build()))
).build())))
.tools(buildTools())
.build();
Response resp = arkService.createResponse(req);
System.out.println(resp);
arkService.shutdownExecutor();
}
}
```
**选项：Go SDK**
```Go
package main
import (
"context"
"fmt"
"io"
"os"
"github.com/volcengine/ark-runtime-go/arkruntime"
"github.com/volcengine/ark-runtime-go/arkruntime/model/responses"
)
func main() {
client := arkruntime.NewClientWithApiKey(
os.Getenv("ARK_API_KEY"),
arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
)
request := &responses.ResponsesRequest{
Model: "doubao-seed-2-1-pro-260915",
Input: responses.NewStringResponsesInput(
"请查询今天的重要 AI 产品发布，并给出来源。",
),
Tools: []responses.Tool{
{
OneOf: responses.NewWebSearchToolToolSum(
responses.WebSearchTool{
Type: responses.WebSearchToolTypeWebSearch,
},
),
},
},
MaxToolCalls: responses.NewOptInt64(1),
}
stream, err := client.CreateResponsesStream(context.Background(), request)
if err != nil {
fmt.Printf("stream error: %v\n", err)
return
}
for {
event, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
fmt.Printf("stream error: %v\n", err)
return
}
switch event.OneOf.Type {
case responses.ResponseTextDeltaEventResponseStreamEventSum:
print(event.OneOf.ResponseTextDeltaEvent.Delta.Or(""))
case responses.ResponseWebSearchCallInProgressEventResponseStreamEventSum:
fmt.Println("web search started")
case responses.ResponseWebSearchCallCompletedEventResponseStreamEventSum:
fmt.Println("web search completed")
}
}
fmt.Println()
}
```
---
## 参数说明
**选项：豆包搜索 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`：限制搜索结果不包含禁止访问的域名列表。
**选项：联网内容插件**
详情请参见 [创建 Responses 模型请求](/docs/create-model-responses-api)。
---
## Agent 场景下的用法
您可以在 Claude Code 或 Codex 中调用豆包搜索 Custom 版工具，该工具兼容 Anthropic Messages 接口协议和 OpenAI Responses API 接口协议。
**选项：Claude Code**
Claude Code 通过兼容 Anthropic Messages 接口协议的服务调用豆包搜索能力。完成接入配置后，在 Claude Code 中对话时，如果模型判断您的问题需要通过搜索功能才能回答，那么模型会调用 Web Search 工具进行搜索。完整的配置和使用方法参见[在 Claude Code 中使用 Web Search 工具](/docs/integrate-third-party-tools#web-search-claude-code)。
> **注意**
>
> 调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。
**选项：Codex**
Codex 通过兼容 OpenAI Responses API 接口协议的服务调用豆包搜索能力。完成接入配置后，在 Codex 中对话时，如果模型判断您的问题需要通过搜索功能才能回答，那么模型会调用 Web Search 工具进行搜索。完整的配置和使用方法参见[在 Codex 中使用 Web Search 工具](/docs/integrate-third-party-tools#web-search-codex)。
> **注意**
>
> 调用 Web Search 工具时，大模型可能会发起额外的 API 请求来总结搜索结果，因此会消耗额外的 token。
## API 调用场景下的用法与配置
本节介绍联网搜索场景中的工具用法与常用配置。不同工具的差异以相关说明为准。
> **注意**
>
> 本节内容仅适用于 Responses API，不适用于 Messages API。
### 开启流式调用
在 response 中设置 `stream=True`，即可开启流式调用，使响应以流式方式返回，从而更快地获取部分结果，同时可实时查看模型判断是否调用搜索的思考过程。
示例：
```Python
response = client.responses.create(
model="doubao-seed-2-1-pro-260915",
input=[ # 输入内容，包含系统提示和用户问题
...
],
tools=[ # 使用工具及参数
...
],
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"`：头条图文。
示例：
```Python
tools=[
{
"type": "web_search", # 配置工具类型为联网内容插件
"sources": ["douyin", "moji", "toutiao"], # 附加搜索来源（抖音百科、墨迹天气、头条图文等平台）
}
],
```
### 指定用户地理位置
您可以在 tools 中设置 `user_location` 字段，并提供用户的国家、地区和城市信息，以优化与地理位置相关的搜索结果。
示例：
```Python
tools=[
{
"type": "web_search", # 配置工具类型为联网内容插件
"user_location": { # 指定用户地理位置（用于优化搜索结果）
"type": "approximate", # 大致位置
"country": "中国",
"region": "浙江",
"city": "杭州"
}
}
],
```
### 设置搜索限制
> **说明**
>
> 以下搜索限制参数仅联网内容插件支持，豆包搜索 Custom 版不支持。即当 `sources` 的值为 `["doubao"]` 时，`tools.limit`、`tools.max_keyword`、`tools.user_location` 均不生效，向它们传入的值将被忽略。
* `tools.`**`max_keyword`**
* 作用：限制单轮搜索中可使用的最大关键词数量。
* 取值范围：`1`～`50`。
* 示例：如果模型原本计划搜索三个关键词（例如“大模型最新进展”、“2025 年科技创新”），但将 `max_keyword` 设置为 `1`，模型将仅使用第一个关键词进行搜索。关于 `max_keyword` 参数的具体使用方法和示例，请参见 [创建模型响应](/docs/create-model-responses-api)。
* `tools.`**`limit`**
* 作用：限制单轮搜索操作返回的最大结果条数。
* 取值范围：`1`～`50`。
* 默认值：`10`。
* 说明：此参数会影响返回内容的规模和请求性能。单次搜索最多可返回 20 条结果，但单轮可能有多次搜索，默认召回 10 条。
* **`max_tool_calls`**
* 作用：限制在一次完整的模型响应中可以执行工具调用的最大轮次。
* 取值范围：`1`～`10`。
* 默认值：`3`。
示例：
```Python
tools = [{
"type": "web_search",
"max_keyword": 2,
"limit": 10,
}]
max_tool_calls = 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` 查看服务端工具发起的联网搜索请求次数。
关于 Responses API 用量参数的详细信息，请参见[创建 Response](/docs/create-model-responses-api)。
### 设置系统提示词
系统提示词的设置对搜索请求的影响较大，建议进行优化以提升搜索的准确性与效率。以下两种系统提示词模板供您参考。
模板 1：
```Plaintext
# 定义系统提示词
system_prompt = """
你是AI个人助手，负责解答用户的各种问题。你的主要职责是：
1. **信息准确性守护者**：确保提供的信息准确无误。
2. **搜索成本优化师**：在信息准确性和搜索成本之间找到最佳平衡。
# 任务说明
## 1. 联网意图判断
当用户提出的问题涉及以下情况时，需使用 `web_search` 进行联网搜索：
- **时效性**：问题需要最新或实时的信息。
- **知识盲区**：问题超出当前知识范围，无法准确解答。
- **信息不足**：现有知识库无法提供完整或详细的解答。
## 2. 联网后回答
- 在回答中，优先使用已搜索到的资料。
- 回复结构应清晰，使用序号、分段等方式帮助用户理解。
## 3. 引用已搜索资料
- 当使用联网搜索的资料时，在正文中明确引用来源，引用格式为：
`[1] (URL地址)`。
## 4. 总结与参考资料
- 在回复的最后，列出所有已参考的资料。格式为：
1. [资料标题](URL地址1)
2. [资料标题](URL地址2)
"""
```
模板 2：
```Plaintext
# 定义系统提示词
system_prompt = """
# 角色
你是AI个人助手，负责解答用户的各种问题。你的主要职责是：
1. **信息准确性守护者**：确保提供的信息准确无误。
2. **回答更生动活泼**：请在模型的回复中多使用适当的 emoji 标签 🌟😊🎉
# 任务说明
## 1. 联网意图判断
当用户提出的问题涉及以下情况时，需使用 `web_search` 进行联网搜索：
- **时效性**：问题需要最新或实时的信息。
- **知识盲区**：问题超出当前知识范围，无法准确解答。
- **信息不足**：现有知识库无法提供完整或详细的解答。
## 2. 联网后回答
- 在回答中，优先使用已搜索到的资料。
- 回复结构应清晰，使用序号、分段等方式帮助用户理解。
## 3. 引用已搜索资料
- 当使用联网搜索的资料时，在正文中明确引用来源，引用格式为：
`[1] (URL地址)`。
## 4. 总结与参考资料
- 在回复的最后，列出所有已参考的资料。格式为：
1. [资料标题](URL地址1)
2. [资料标题](URL地址2)
"""
```
---
## 注意事项
* 自定义函数名称应避免使用 `web_search`，否则模型可能按内置工具优先级判断调用逻辑。
* `doubao` 只能单独配置，不能与 `toutiao`、`douyin`、`moji` 或 `search_engine` 等其他搜索来源同时使用。
* 豆包搜索 Custom 版支持 Responses API 和 Messages API；联网内容插件仅支持 Responses API。
* 联网内容插件是否触发搜索由模型判断。一轮搜索可能发起多个关键词搜索，可以通过 `max_keyword` 参数限制一轮搜索的关键词数量，以控制调用频次和成本。
* 豆包搜索 Custom 版和联网内容插件均不支持 `caching` 参数，该参数不可与 `tools` 参数一起使用，否则会返回 `400` 错误。
## 相关文档
* 计费
* 豆包搜索 Custom 版
* 普通 API 调用场景：[豆包搜索产品计费](https://docs.volcengine.com/docs/87772/2272951?lang=zh#yQ0Kqmsy)
* Agent Plan 场景：[套餐内 AFP 抵扣规则](/docs/agent-plan-personal-afp-credits-billing-rules)、[超额后付费规则](/docs/agent-plan-personal-over-quota-postpaid-rules)
* Coding Plan 场景：[套餐概览](/docs/coding-plan-personal-plan-overview)
* 联网内容插件：按联网内容插件实际使用次数计费。具体收费标准详见[联网内容插件产品计费](/docs/online-content-plugin-pricing)。
* Agent 场景使用方法
* [在 Claude Code 中使用 Web Search 工具](/docs/integrate-third-party-tools#web-search-claude-code)
* [在 Codex 中使用 Web Search 工具](/docs/integrate-third-party-tools#web-search-codex)
* API 参考
* [创建 Response](/docs/create-model-responses-api)
* [创建 Message](/docs/messages-api)
* 错误码说明：[错误码](/docs/error-codes)