Build a Deep Research Agent in 15 Lines with the Claude Agent SDK

Anthropic published a first-party research agent cookbook in the Claude Agent SDK. It covers three distinct tiers of research agent architecture, from a single-function stateless query to a production-packaged module with parallel subagents. This post walks through all three tiers, adds opinionated guidance on system prompt design, and covers failure modes and cost management — things the cookbook covers partially but leaves to the reader to fill in.

This is a code walkthrough based on documented SDK behavior. The code patterns shown are drawn from Anthropic’s published cookbook at platform.claude.com/cookbook/claude-agent-sdk-00-the-one-liner-research-agent. We are not describing the output of a test we ran; we are explaining the architecture described in first-party documentation.

The three tiers

Tier 1: the one-liner stateless query

The Claude Agent SDK cookbook opens with the stateless research pattern:

async for msg in query(
    prompt="What are the key differences between LangGraph and CrewAI?",
    options=ClaudeAgentOptions(allowed_tools=["WebSearch"])
):
    print(msg)

This is genuinely useful for one-off research tasks. The query() function handles session management, tool routing, and streaming output automatically. The allowed_tools=["WebSearch"] parameter pre-approves web search without requiring a separate MCP server config.

The limitation is in the name: stateless. Each call is independent. There is no memory of previous queries, no ability to build on earlier findings, and no checkpointing if the query runs long. For simple fact-finding or quick competitive lookups, this is the right tier. For investigation that spans multiple queries and builds a cumulative understanding, you need Tier 2.

Tier 2: the stateful ClaudeSDKClient

The ClaudeSDKClient enables multi-turn stateful research — the agent maintains context across a conversation and can build on earlier findings:

client = ClaudeSDKClient(
    system_prompt="""You are a research assistant. When you find information,
    cite your sources inline. Flag any claim you cannot verify with [UNVERIFIED].
    End each response with a confidence assessment: HIGH / MEDIUM / LOW."""
)

# First query establishes context
response_1 = await client.query("What is LangGraph's production deployment footprint?")

# Second query builds on the first
response_2 = await client.query(
    "Given what we found, how does that compare to CrewAI's usage patterns?"
)

The system prompt is where citation discipline lives. The pattern above — inline citations, explicit [UNVERIFIED] flags, and a confidence assessment — is the minimum viable citation system for a research agent you intend to trust. Without explicit citation instructions, Claude will produce accurate-sounding summaries that may not reflect verifiable sources.

The continue_conversation=True parameter in the production module (Tier 3) enables persistent sessions across script invocations — important for research workflows that span hours or days.

Tier 3: parallel subagents for competitive analysis

Anthropic’s multi-agent research system — Opus as orchestrator, Sonnet subagents for parallel exploration — is documented to produce a 90.2% improvement over single-agent Opus on internal research evaluations. The architecture:

async def deep_research(topic: str) -> ResearchReport:
    # Orchestrator: plans the research dimensions
    dimensions = await orchestrator.plan_research(topic)

    # Parallel subagents: each investigates one dimension
    tasks = [
        subagent.investigate(dimension)
        for dimension in dimensions
    ]
    findings = await asyncio.gather(*tasks)

    # Orchestrator: synthesizes into final report
    return await orchestrator.synthesize(findings)

The 90.2% improvement figure is from Anthropic’s internal evaluation — it is not a figure we can reproduce independently, and the evaluation methodology is not published. The architectural principle it illustrates — that parallel investigation of research dimensions produces better coverage than sequential single-agent research — is well-grounded in the multi-agent literature regardless of the specific percentage.

Cost management

The Claude Agent SDK provides three cost control mechanisms documented in the SDK overview:

• max_budget_usd: hard cap on total spend per agent session
• allowed_tools: pre-approval list that prevents the agent from acquiring expensive tools you did not intend to give it
• max_buffer_size: limits context accumulation in multimodal research involving base64-encoded images and PDFs

For a research agent doing web searches, a reasonable starting budget is $0.50–$2.00 per deep research session depending on scope. Parallel subagent architectures multiply cost by the number of subagents — a five-subagent research run costs approximately five times the per-subagent cost. Set max_budget_usd before deploying any parallel architecture.

OpenAI’s Deep Research (updated February 10, 2026) allows users to restrict web searches to trusted sites and interrupt runs mid-flight to refine with follow-up prompts. These features represent the user-experience ceiling the Claude Agent SDK research pattern is reaching toward — the underlying agent capability is comparable, but the UX affordances for mid-run intervention are currently better on OpenAI’s managed product.

System prompt design for citation discipline

The weakest point in most research agent implementations is citation handling. Without explicit instructions, the agent will produce confident-sounding text that may or may not reflect verifiable sources. The minimum viable citation system:

When you state a fact:
1. Cite the source URL inline, immediately after the claim, in [brackets]
2. If you cannot find a source URL, write [UNVERIFIED]
3. Do not summarize unverified claims as if they were confirmed
4. If two sources conflict, report the conflict — do not silently pick one

This instruction set catches the most common failure modes: fabricated statistics, confident misattributions, and unsourced synthesis presented as fact. It does not catch everything — an agent can still hallucinate source URLs — but it creates an output format you can audit.

NVIDIA’s technical blog documented adding a deep research skill to agent harnesses including Hermes and Claude Code, confirming that the citation discipline pattern is cross-platform. The system prompt instructions above work the same way regardless of which SDK you are using.

When to use each tier

Common questions

How does the Claude Agent SDK research pattern compare to OpenAI's Deep Research?

OpenAI's Deep Research (updated February 10, 2026) is a managed product with a polished UI — users can restrict web searches to trusted sites, interrupt runs mid-flight, and connect the tool to any MCP or app. The Claude Agent SDK research pattern gives you more programmatic control and is better for embedding research capability into your own tools. OpenAI's product is better for end-user-facing research workflows where UX matters more than programmability.

What is the Claude Agent SDK's Python repository star count?

Approximately 4,800 GitHub stars as of March 2026, with the npm package exceeding 600 dependents and 130+ versions published. The star count is lower than LangGraph or CrewAI but the release cadence is fast — the SDK is actively developed.

Can I run the Tier 3 architecture on a free API tier?

Parallel subagent architectures generate significant API usage rapidly. A five-subagent research run on a moderately complex topic will likely exceed the free tier in a single session. Use max_budget_usd to set an explicit cap and monitor your dashboard during the first few runs.

How do I add domain-specific knowledge to a research agent?

Two approaches: (1) include domain-specific context in the system prompt — if you are researching regulatory filings, include the relevant regulatory body names, document types, and terminology; (2) use an MCP server that connects the agent to a domain-specific database or document store. The MCP approach is more scalable but requires an MCP server that exposes your knowledge base.