Web Search 工具让 Grok 能够实时搜索网络并浏览网页以查找信息。该工具允许模型搜索互联网、访问网页并提取相关信息，以最新内容回答查询。

SDK 支持

SDK/API	工具名称
xAI SDK	`web_search`
OpenAI Responses API	`web_search`
Vercel AI SDK	`xai.tools.webSearch()`

所有与 Responses API 兼容的 SDK 也支持此工具。

基础用法

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import web_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",  # reasoning model
    tools=[web_search()],
    include=["verbose_streaming"],
)

chat.append(user("What is xAI?"))

is_thinking = True
for response, chunk in chat.stream():
    for tool_call in chunk.tool_calls:
        print(f"\\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")
    if response.usage.reasoning_tokens and is_thinking:
        print(f"\\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)
    if chunk.content and is_thinking:
        print("\\n\\nFinal Response:")
        is_thinking = False
    if chunk.content and not is_thinking:
        print(chunk.content, end="", flush=True)

print("\\n\\nCitations:")
print(response.citations)

import os
from openai import OpenAI

api_key = os.getenv("XAI_API_KEY")
client = OpenAI(
    api_key=api_key,
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.7",
    input=[
        {
            "role": "user",
            "content": "What is xAI?",
        },
    ],
    tools=[
        {
            "type": "web_search",
        },
    ],
)

print(response)

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What is xAI?',
  tools: {
    web_search: xai.tools.webSearch(),
  },
});

console.log(text);
console.log('Citations:', sources);

curl https://api.x.ai/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
  "model": "grok-4.7",
  "input": [
    {
      "role": "user",
      "content": "What is xAI?"
    }
  ],
  "tools": [
    {
      "type": "web_search"
    }
  ]
}'

Web Search 参数

参数	说明
`allowed_domains`	仅在指定域名内搜索（最多 5 个）
`excluded_domains`	从搜索中排除指定域名（最多 5 个）
`enable_image_understanding`	启用对浏览过程中发现图像的分析
`enable_image_search`	启用可嵌入响应的图像搜索结果

仅在指定域名中搜索

使用 allowed_domains，使 web search 仅在指定域名范围内的网页上执行搜索和浏览。

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import web_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",
    tools=[
        web_search(allowed_domains=["grokipedia.com"]),
    ],
)

chat.append(user("What is xAI?"))
# stream or sample the response...

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "What is xAI?"}],
    tools=[
        {
            "type": "web_search",
            "filters": {"allowed_domains": ["grokipedia.com"]},
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What is xAI?',
  tools: {
    web_search: xai.tools.webSearch({
      allowedDomains: ['grokipedia.com'],
    }),
  },
});

排除指定域名

使用 excluded_domains，防止模型在任何 web search tool invocation 中包含指定域名。

chat = client.chat.create(
    model="grok-4.7",
    tools=[
        web_search(excluded_domains=["grokipedia.com"]),
    ],
)

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "What is xAI?"}],
    tools=[
        {
            "type": "web_search",
            "filters": {"excluded_domains": ["grokipedia.com"]},
        },
    ],
)

启用图像理解

将 enable_image_understanding 设置为 true，会让 Agent 能够访问 view_image tool，从而分析搜索过程中遇到的图像。

启用后，会在 SERVER_SIDE_TOOL_VIEW_IMAGE 中看到 response.server_side_tool_usage，以及其调用次数。

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import web_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",
    tools=[
        web_search(enable_image_understanding=True),
    ],
)

chat.append(user("What is included in the image in xAI's official website?"))
# stream or sample the response...

response = client.responses.create(
    model="grok-4.7",
    input=[
        {
            "role": "user",
            "content": "What is included in the image in xAI's official website?",
        },
    ],
    tools=[
        {
            "type": "web_search",
            "enable_image_understanding": True,
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: "What is included in the image in xAI's official website?",
  tools: {
    web_search: xai.tools.webSearch({
      enableImageUnderstanding: true,
    }),
  },
});

启用 Image Search

将 enable_image_search 设置为 true，可让 Grok 搜索相关图像，并以 Markdown image embed 的形式将其包含在 response 中，例如 ![alt](url)。

Vercel AI SDK 尚未公开 enableImageSearch；以下示例使用 Responses API 和 xAI Python SDK。

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4.7",
  "input": [
    {
      "role": "user",
      "content": "Show me images of Starship on the launch pad."
    }
  ],
  "tools": [
    {
      "type": "web_search",
      "enable_image_search": true
    }
  ]
}'

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import web_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",
    tools=[
        web_search(enable_image_search=True),
    ],
)

chat.append(user("Show me images of Starship on the launch pad."))
response = chat.sample()
print(response.content)
print(response.server_side_tool_usage)

response = client.responses.create(
    model="grok-4.7",
    input=[
        {
            "role": "user",
            "content": "Show me images of Starship on the launch pad.",
        },
    ],
    tools=[
        {
            "type": "web_search",
            "enable_image_search": True,
        },
    ],
)

print(response)

Response 可以直接在输出文本中包含 Markdown image embed：

![Why the SpaceX Starship launch pad matters](https://www.astronomy.com/wp-content/uploads/2024/09/starship-test-flight-mission-scaled.jpg)

Here are several high-quality images of SpaceX's Starship on the launch pad at Starbase in Boca Chica, Texas.

在 xAI SDK 中，成功执行的 image search 会以 response.server_side_tool_usage 的形式出现在 SERVER_SIDE_TOOL_IMAGE_SEARCH。

引用

有关如何获取和使用搜索结果引用的详情，请参阅引用页面。

最后更新：2026 年 5 月 27 日