Add XSearchTool built-in tool for X/Twitter search via Grok provider

[colesmcintosh]

Description

Add XSearchTool as a new built-in tool that enables Grok-powered agents to search X/Twitter posts, user profiles, and threads natively. This is a unique capability only available through X AI's Grok models.

Motivation

X AI's Grok models offer the only LLM provider with native access to real-time X/Twitter data. This enables use cases not possible with any other provider:

• Real-time social media search - Search posts, threads, and user content on X
• Date-range filtering - Query posts within specific time windows
• Handle-based filtering - Include or exclude specific X accounts
• Multimedia understanding - Analyze images and videos embedded in posts

Proposed code

from pydantic_ai import Agent, XSearchTool

agent = Agent(
    'grok:grok-4-1-fast',
    builtin_tools=[
        XSearchTool(
            allowed_x_handles=['pydantic'],  # Max 10 handles
            from_date='2025-01-01',
            to_date='2025-06-01',
            enable_image_understanding=True,
            enable_video_understanding=True,
        )
    ]
)

result = agent.run_sync('What are the latest Pydantic AI updates on X?')
print(result.output)

Provider Support

Only XAI/Grok

References

• X AI Search Tools Documentation
• Existing Grok provider
• Built-in tools pattern

[dsfaccini]

hey @colesmcintosh this is a cool request! Would you be open to contributing this?

[colesmcintosh]

Hey @dsfaccini - yes, would love to!

[colesmcintosh]

@dsfaccini

I've been working on implementing this and discovered an important detail:

The Issue

The X AI x_search tool only works with the Responses API (/v1/responses), not the Chat Completions API (/v1/chat/completions).

The X AI documentation shows using client.responses.create() with tools=[{"type": "x_search", ...}], which maps to Pydantic AI's OpenAIResponsesModel, not OpenAIChatModel.

This means to use XSearchTool, users would need to use grok-responses:grok-4-1-fast instead of grok:grok-4-1-fast.

Question for Maintainers

Should we:

1. Add a new grok-responses provider alias that routes to OpenAIResponsesModel (similar to how openai-responses works), keeping grok: for Chat Completions?

2. Or automatically use the Responses API when XSearchTool is detected in builtin_tools?

Proposed Approach

I'm thinking this might be better split into two separate PRs:

1. PR 1: Add grok-responses provider support to enable actually using the tool
2. PR 2: Add XSearchTool class, documentation, and tests (the tool definition itself)

This would keep the changes focused and easier to review.

---

Thoughts?

[dsfaccini]

Hey @colesmcintosh I appreciate the info, will look into it. Either way probably better to keep it all in one PR, since a PR only introducing a "grok-responses" provider would be pretty bare.

Will get back to you!

[colesmcintosh]

Hey @dsfaccini! No rush at all, just wanted to check in since it's been a few days. Totally understand things are probably busy on your end. If it's helpful, I'm happy to put together a rough PR to get this started. Also, regarding your point about keeping it in one PR, that makes total sense.

[dsfaccini]

hey @colesmcintosh appreciate you bubbling this up again. I haven't had time to look into it, but I guess the question that I'd like to answer is whether we can migrate all of x-ai usage onto the responses format so that we don't have to maintain two different "grok"s.

would you be fine answering that question in your PR?

[colesmcintosh]

@dsfaccini Yep, totally fine with that. I can explore whether all x-ai usage can migrate cleanly to the responses format and call out any gaps or tradeoffs in the PR so we’re not maintaining two paths. For what it’s worth, the x-ai docs already frame completions as legacy and position responses as the primary API. In their docs, they note: “Chat Responses is the preferred way of interacting with our models via API.”

[DouweM]

Note that X.ai are contributing a new XaiProvider using their SDK that is awaiting my review: #3400. It doesn't currently support the X Search tool, but that should be relatively easy to add. I recommend waiting until that lands instead of adding to the to-be-deprecated GrokProvider :)

[colesmcintosh]

Thanks for the heads-up, @DouweM! I’ll hold off on the GrokProvider changes and wait for #3400 to land, then can add XSearchTool support on top of the new XaiProvider.