X Search tool 使 Grok 能够在 X（原 Twitter）上执行 keyword search、semantic search、user search 和 thread fetch。该 tool 允许 model 访问实时社交媒体内容、分析帖子并从 X 的海量数据中获取洞察。

SDK 支持

SDK/API	Tool 名称
xAI SDK	`x_search`
OpenAI Responses API	`x_search`
Vercel AI SDK	`xai.tools.xSearch()`

所有与 Responses API 兼容的 SDK 也支持该 tool。

基础用法

import os

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

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

chat.append(user("What are people saying about xAI on X?"))

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.5",
    input=[
        {
            "role": "user",
            "content": "What are people saying about xAI on X?",
        },
    ],
    tools=[
        {
            "type": "x_search",
        },
    ],
)

print(response)

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

const { text, sources } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'What are people saying about xAI on X?',
  tools: {
    x_search: xai.tools.xSearch(),
  },
});

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.5",
  "input": [
    {
      "role": "user",
      "content": "What are people saying about xAI on X?"
    }
  ],
  "tools": [
    {
      "type": "x_search"
    }
  ]
}'

X Search 参数

参数	说明
`allowed_x_handles`	仅考虑来自指定 X handle 的帖子（最多 20 个）
`excluded_x_handles`	排除来自指定 X handle 的帖子（最多 20 个）
`from_date`	搜索范围开始日期（ISO8601 格式）
`to_date`	搜索范围结束日期（ISO8601 格式）
`enable_image_understanding`	启用对帖子中图像的分析
`enable_video_understanding`	启用对帖子中视频的分析

仅考虑指定 Handle 的帖子

使用 allowed_x_handles，仅考虑来自给定 X handle 列表的帖子。最多可包含 20 个 handle。

import os

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

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(allowed_x_handles=["elonmusk"]),
    ],
)

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

response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "What is the current status of xAI?"}],
    tools=[
        {
            "type": "x_search",
            "allowed_x_handles": ["elonmusk"],
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'What is the current status of xAI?',
  tools: {
    x_search: xai.tools.xSearch({
      allowedXHandles: ['elonmusk'],
    }),
  },
});

排除指定 Handle 的帖子

使用 excluded_x_handles，防止 model 在任何 X search tool invocation 中包含来自指定 handle 的帖子。最多可排除 20 个 handle。

chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(excluded_x_handles=["elonmusk"]),
    ],
)

response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "What is the current status of xAI?"}],
    tools=[
        {
            "type": "x_search",
            "excluded_x_handles": ["elonmusk"],
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'What is the current status of xAI?',
  tools: {
    x_search: xai.tools.xSearch({
      excludedXHandles: ['elonmusk'],
    }),
  },
});

日期范围

可以通过指定 from_date 和 to_date 限制搜索数据的日期范围。数据会被限制在从 from_date 到 to_date 的时间段内，包含两个日期。

两个字段都必须使用 ISO8601 格式，例如 "YYYY-MM-DD"。如果使用 xAI Python SDK，from_date 和 to_date 字段可以通过 datetime.datetime object 传入。

import os
from datetime import datetime

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

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(
            from_date=datetime(2025, 10, 1),
            to_date=datetime(2025, 10, 10),
        ),
    ],
)

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

response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "What is the current status of xAI?"}],
    tools=[
        {
            "type": "x_search",
            "from_date": "2025-10-01",
            "to_date": "2025-10-10",
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'What is the current status of xAI?',
  tools: {
    x_search: xai.tools.xSearch({
      fromDate: '2025-10-01',
      toDate: '2025-10-10',
    }),
  },
});

启用 Image Understanding

将 enable_image_understanding 设置为 true，允许 Agent 分析搜索过程中遇到的 X 帖子中的图像。

chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(enable_image_understanding=True),
    ],
)

response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "Find X posts with images about AI"}],
    tools=[
        {
            "type": "x_search",
            "enable_image_understanding": True,
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'Find X posts with images about AI',
  tools: {
    x_search: xai.tools.xSearch({
      enableImageUnderstanding: true,
    }),
  },
});

启用 Video Understanding

将 enable_video_understanding 设置为 true，允许 Agent 分析 X 帖子中的视频。该功能仅适用于 X Search，不适用于 Web Search。

chat = client.chat.create(
    model="grok-4.5",
    tools=[
        x_search(enable_video_understanding=True),
    ],
)

response = client.responses.create(
    model="grok-4.5",
    input=[{"role": "user", "content": "Find X posts with videos about AI"}],
    tools=[
        {
            "type": "x_search",
            "enable_video_understanding": True,
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'Find X posts with videos about AI',
  tools: {
    x_search: xai.tools.xSearch({
      enableVideoUnderstanding: true,
    }),
  },
});

Citation

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