The one-liner research agent Sep 2025 • Claude Agent SDK Agent Patterns Build a research agent using Claude Code SDK with WebSearch for autonomous research.

This cookbook teaches how to build a research agent using Claude Agent SDK with WebSearch tool for autonomous information gathering and synthesis. The guide demonstrates creating a functional research agent in just a few lines of code, then progresses to production improvements including conversation memory, system prompts for specialized behavior, and multimodal research capabilities. The agent autonomously decides when and how to search, follows promising leads, and synthesizes findings without predefined workflows.

Key Points

• •Research agents are ideal for tasks where information isn't self-contained and the exploration path emerges during investigation, not predetermined
• •Use the query() function for stateless, one-off research tasks; use ClaudeSDKClient for multi-turn investigations requiring conversation memory and context
• •The allowed_tools parameter controls which tools Claude can use autonomously—WebSearch is enabled by default for research agents
• •Implement system prompts to encode domain-specific research standards, citation formats, and output structure requirements
• •Enable the Read tool for multimodal research to analyze images, PDFs, charts, and diagrams alongside text-based search results
• •Agent autonomously decides when to search, what queries to run, and how to synthesize results without human intervention
• •Visualization utilities (print_activity, display_agent_response, visualize_conversation) help monitor agent actions and understand decision-making in real-time
• •Stateless queries work well for parallel processing of independent research tasks but fail for iterative refinement based on previous findings
• •Research agents adapt their strategy based on discoveries, follow promising leads, and know when sufficient information has been gathered

Workflow Diagram

Concepts

Artifacts (3)

from utils.agent_visualizer import (
    display_agent_response,
    print_activity,
)
from claude_agent_sdk import ClaudeAgentOptions, query

MODEL = "claude-opus-4-6"

messages = []
async for msg in query(
    prompt="Research the latest trends in AI agents and give me a brief summary and relevant citations links.",
    options=ClaudeAgentOptions(
        model=MODEL,
        allowed_tools=["WebSearch"]
    ),
):
    print_activity(msg)
    messages.append(msg)

display_agent_response(messages)

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

RESEARCH_SYSTEM_PROMPT = """You are a research agent specialized in AI. When providing research findings:
- Always include source URLs as citations
- Format citations as markdown links: [Source Title](URL)
- Group sources in a "Sources:" section at the end of your response"""

MODEL = "claude-opus-4-6"

messages = []
async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model=MODEL,
        cwd="research_agent",
        system=RESEARCH_SYSTEM_PROMPT,
        allowed_tools=["WebSearch", "Read"]
    )
) as client:
    # Multi-turn research with conversation memory
    response = await client.query(
        prompt="Research the latest trends in AI agents and give me a brief summary and relevant citations links."
    )
    messages.append(response)

# Install required dependencies
pip install -U claude-agent-sdk python-dotenv

# Create .env file with API key
echo "ANTHROPIC_API_KEY=your_key_here" > .env