Sign in Subscribe
Deep Research

Emulating xAI Grok’s DeepSearch with OpenAI Agents SDK

Kaizhi Tang

• 3 min read

Why “DeepSearch” matters

xAI’s Grok introduced a DeepSearch mode that blends an LLM with live retrieval (web + platform data) so the model can answer with up‑to‑date context rather than being limited by a training cutoff. Conceptually it’s a modern retrieval‑augmented generation (RAG) system plus an agent loop: the model decides when to search, which sources to open, how to reconcile conflicts, and when it has enough evidence to answer.

This article shows how to build a similar “ask once → research → synthesize” workflow using the OpenAI Agents SDK.

A practical reference architecture

A Grok‑style DeepSearch experience typically needs five building blocks:

  1. Agent loop: the model alternates between reasoning and calling tools until it produces a final answer.
  2. Search: web search to discover sources.
  3. Read: fetch and extract relevant page content (or PDFs) for grounding.
  4. Synthesis: merge multiple sources into a structured output with citations.
  5. Guardrails & observability: limits, logging, and evaluation so it’s reliable and debuggable.

OpenAI’s Agents SDK provides (1) natively, and offers hosted tools for (2) and (optionally) (3)/(RAG). You can add your own tools for anything else.

Step-by-step: build a DeepSearch-style agent

1) Install and set up

Python:

pip install openai-agents

Minimal imports (tool names may evolve; follow the SDK docs for the exact APIs):

from agents import Agent, Runner
from agents.tools import WebSearchTool, FileSearchTool

Give the agent a web-search tool so it can discover current sources.

research_agent = Agent(
    name="DeepSearchResearcher",
    instructions=(
        "You are a research agent. For complex questions: "
        "(1) search the web, (2) open and extract key passages, "
        "(3) cross-check across multiple sources, "
        "(4) write a structured answer with citations and a References section."
    ),
    tools=[WebSearchTool()],
)

result = Runner.run_sync(research_agent, "What’s new in OpenAI Agents SDK in the last 3 months?")
print(result.final_output)

Design tip: in your instructions, force multiple sources (e.g., “use at least 3 independent sources for factual claims”), and require the model to explicitly label uncertainty.

3) Add RAG over your own documents (optional)

If you have internal docs (policies, notes, research PDFs) you want included, add a retrieval tool.

vector_tool = FileSearchTool(
    vector_store_ids=["<YOUR_VECTOR_STORE_ID>"],
    max_num_results=5,
)
research_agent.tools.append(vector_tool)

Your agent can now mix public web sources with private/internal documents.

4) Add custom tools (APIs, databases, browser automation)

DeepSearch products feel “smart” because the agent can do more than search. The Agents SDK lets you expose your own functions as tools (e.g., query a database, call a SaaS API, run a scraper, or invoke a headless browser) and let the agent decide when to use them.

Typical DeepSearch-adjacent tools:

  • Fetch & extract: take a URL and return clean text + metadata
  • PDF parsing: extract text + headings + page numbers
  • Entity lookup: knowledge graph / company database
  • Code execution: for data analysis and chart creation

Rule of thumb: tools should be deterministic, return small outputs, and include source metadata (URL, title, timestamp) so citations are easy.

5) Make outputs “report-like” (and cite sources)

A usable DeepSearch result isn’t just long—it’s structured.

In your instructions, require:

  • a short Executive summary
  • Key findings bullets
  • a What we know / What we don’t know section
  • a final ## References list with URLs

Also require citations for each non-trivial factual claim (inline footnotes or parenthetical links).

6) Add guardrails and cost controls

DeepSearch can get expensive and can hallucinate confidently if you don’t constrain it.

Practical controls:

  • Max turns (tool calls) per request
  • Max sources and max tokens per source (extract only the relevant sections)
  • Stop conditions (“if two sources disagree, do not guess—present both and explain”)
  • Caching for repeated URLs/queries

7) Observability and evaluation

Treat the agent like a production service:

  • Log every tool call (query, URL, timestamp)
  • Store the extracted snippets used for synthesis
  • Add “golden question” evals (does it cite? does it quote accurately? does it avoid invented sources?)

What this replicates (and what it doesn’t)

This pattern reproduces the core DeepSearch experience:

  • LLM + live retrieval (web search)
  • Autonomous, multi-step tool use (agent loop)
  • Grounded synthesis (citations + References)

What you won’t automatically get without extra engineering:

  • a tuned ranking model for “best sources”
  • robust browsing for highly dynamic sites
  • anti-bot handling / session management
  • domain-specific evaluation and guardrails

Those are solvable, but they live outside the basic SDK setup.

References

  1. TechTarget — “Grok 3 model explained: Everything you need to know” (mentions Think/DeepSearch modes and DeepSearch as internet-scouring retrieval): https://www.techtarget.com/whatis/feature/Grok-3-model-explained-Everything-you-need-to-know
  2. Wikipedia — “Grok (chatbot)” (overview, including DeepSearch mention): https://en.wikipedia.org/wiki/Grok_(chatbot)
  3. OpenAI Agents SDK docs (overview and primitives): https://openai.github.io/openai-agents-python/
  4. OpenAI Agents SDK tools docs (WebSearchTool / FileSearchTool patterns): https://openai.github.io/openai-agents-python/tools/
  5. OpenAI Agents SDK GitHub (Runner / loop examples): https://github.com/openai/openai-agents-python