工具
网络搜索
网络搜索工具使 Grok 能够实时搜索网络并浏览网页以查找信息。这个强大的工具允许模型搜索互联网、访问网页并提取相关信息，以提供包含最新内容的回答。
SDK 支持
| SDK/API | 工具名称 |
|---|---|
| xAI SDK | web_search |
| OpenAI Responses API | web_search |
| Vercel AI SDK | xai.tools.webSearch() |
此工具也支持所有与 Responses API 兼容的 SDK。
基本用法
python
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.5", # 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)python
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.5",
input=[
{
"role": "user",
"content": "What is xAI?",
},
],
tools=[
{
"type": "web_search",
},
],
)
print(response)javascript
import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';
const { text, sources } = await generateText({
model: xai.responses('grok-4.5'),
prompt: 'What is xAI?',
tools: {
web_search: xai.tools.webSearch(),
},
});
console.log(text);
console.log('Citations:', sources);bash
curl https://api.x.ai/v1/responses \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer $XAI_API_KEY" \\
-d '{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": "What is xAI?"
}
],
"tools": [
{
"type": "web_search"
}
]
}'网络搜索参数
| 参数 | 描述 |
|---|---|
allowed_domains | 仅在特定域名内搜索（最多5个） |
excluded_domains | 从搜索中排除特定域名（最多5个） |
enable_image_understanding | 启用对浏览过程中找到的图像进行分析 |
enable_image_search | 启用可嵌入到回复中的图像搜索结果 |
仅在特定域名中搜索
使用 allowed_domains 使网络搜索仅在指定域名内的网页上执行搜索和网络浏览。
NOTE
在同一请求中，allowed_domains 不能与 excluded_domains 同时设置。
python
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.5",
tools=[
web_search(allowed_domains=["grokipedia.com"]),
],
)
chat.append(user("What is xAI?"))
# stream or sample the response...python
response = client.responses.create(
model="grok-4.5",
input=[{"role": "user", "content": "What is xAI?"}],
tools=[
{
"type": "web_search",
"filters": {"allowed_domains": ["grokipedia.com"]},
},
],
)javascript
const { text } = await generateText({
model: xai.responses('grok-4.5'),
prompt: 'What is xAI?',
tools: {
web_search: xai.tools.webSearch({
allowedDomains: ['grokipedia.com'],
}),
},
});排除特定域名
使用 excluded_domains 防止模型在任何网络搜索工具调用中包含指定的域名。
python
chat = client.chat.create(
model="grok-4.5",
tools=[
web_search(excluded_domains=["grokipedia.com"]),
],
)python
response = client.responses.create(
model="grok-4.5",
input=[{"role": "user", "content": "What is xAI?"}],
tools=[
{
"type": "web_search",
"filters": {"excluded_domains": ["grokipedia.com"]},
},
],
)启用图像理解
将 enable_image_understanding 设置为 true，使代理能够访问 view_image 工具，从而分析在搜索过程中遇到的图像。
启用后，您将在 response.server_side_tool_usage 中看到 SERVER_SIDE_TOOL_VIEW_IMAGE 以及它被调用的次数。
NOTE
如果请求中也包含 X Search 工具，为网络搜索启用此参数也将启用图像理解功能。
python
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.5",
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...python
response = client.responses.create(
model="grok-4.5",
input=[
{
"role": "user",
"content": "What is included in the image in xAI's official website?",
},
],
tools=[
{
"type": "web_search",
"enable_image_understanding": True,
},
],
)javascript
const { text } = await generateText({
model: xai.responses('grok-4.5'),
prompt: "What is included in the image in xAI's official website?",
tools: {
web_search: xai.tools.webSearch({
enableImageUnderstanding: true,
}),
},
});启用图像搜索
将 enable_image_search 设置为 true，让 Grok 搜索相关图像并将它们作为 Markdown 图像嵌入（如 ）包含在回复中。
NOTE
Grok 搜索图像后，返回的图像会包含在用于编写回复的模型上下文中。这与 enable_image_understanding 不同，后者允许 Grok 检查在浏览常规网页时找到的图像。
Vercel AI SDK 尚未暴露 enableImageSearch；下面的示例使用 Responses API 和 xAI Python SDK。
bash
curl https://api.x.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $XAI_API_KEY" \
-d '{
"model": "grok-4.5",
"input": [
{
"role": "user",
"content": "Show me images of Starship on the launch pad."
}
],
"tools": [
{
"type": "web_search",
"enable_image_search": true
}
]
}'python
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.5",
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)python
response = client.responses.create(
model="grok-4.5",
input=[
{
"role": "user",
"content": "Show me images of Starship on the launch pad.",
},
],
tools=[
{
"type": "web_search",
"enable_image_search": True,
},
],
)
print(response)回复可以直接在输出文本中包含 Markdown 图像嵌入：
text
Here are several high-quality images of SpaceX's Starship on the launch pad at Starbase in Boca Chica, Texas.在 xAI SDK 中，成功的图像搜索执行会出现在 response.server_side_tool_usage 中，作为 SERVER_SIDE_TOOL_IMAGE_SEARCH。
引用
有关如何检索和使用搜索结果中的引用的详细信息，请参阅 引用 页面。