Building a One-Liner Research Agent

Research tasks consume hours of expert time: market analysts manually gathering competitive intelligence, legal teams tracking regulatory changes, engineers investigating bug reports across documentation. The core challenge isn’t finding information but knowing what to search for next based on what you just discovered.

The Claude Agent SDK makes it possible to build agents that autonomously explore external systems without a predefined workflow. Unlike traditional workflow automations that follow fixed steps, research agents adapt their strategy based on what they find–following promising leads, synthesizing conflicting sources, and knowing when they have enough information to answer the question.

By the end of this cookbook, you’ll be able to:

Build a research agent that autonomously searches and synthesizes information with a few lines of code

This foundation applies to any task where the information needed isn’t available upfront: competitive analysis, technical troubleshooting, investment research, or literature reviews.

Why Research Agents?

Research is an ideal agentic use case for two reasons:

Information isn’t self-contained. The input question alone doesn’t contain the answer. The agent must interact with external systems (search engines, databases, APIs) to gather what it needs.
The path emerges during exploration. You can’t predetermine the workflow. Whether an agent should search for company financials or regulatory filings depends on what it discovers about the business model. The optimal strategy reveals itself through investigation.

In its simplest form, a research agent searches the web and synthesizes findings. Below, we’ll build exactly that with the Claude Agent SDK’s built-in web search tool in just a few lines of code.

Note: You can also view the full list of Claude Code’s built-in tools

Prerequisites

Before following this guide, ensure you have:

Required Knowledge

Python fundamentals - comfortable with async/await, functions, and basic data structures
Basic understanding of agentic patterns - we recommend reading Building effective agents first if you’re new to agents

Required Tools

Python 3.11 or higher
Anthropic API key (get one here)

Recommended: * Familiarity with the Claude Agent SDK concepts * Understanding of tool use patterns in LLMs

Setup

First, install the required dependencies:

%%capture%pip install -U claude-agent-sdk python-dotenv

Note: Ensure your .env file contains:

ANTHROPIC_API_KEY=your_key_here

Load your environment variables and configure the client:

from dotenv import load_dotenv

load_dotenv()

MODEL = "claude-opus-4-6"

Building Your First Research Agent

Let’s start with the simplest possible implementation: a research agent that can search the web and synthesize findings. With the Claude Agent SDK, this takes just a few lines of code.

The key is the query() function, which creates a stateless agent interaction. We’ll provide Claude with a single tool, WebSearch, and let it autonomously decide when and how to use it based on our research question.

from utils.agent_visualizer import (
    display_agent_response,
    print_activity,
)

from claude_agent_sdk import ClaudeAgentOptions, query

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

🤖 Using: WebSearch()
🤖 Using: WebSearch()
🤖 Using: WebSearch()
✓ Tool completed
✓ Tool completed
✓ Tool completed
🤖 Thinking...

display_agent_response(messages)

Agent Response

Latest Trends in AI Agents (2025) - Summary

🚀 Market Growth & Adoption

The AI agent market is experiencing explosive growth, nearly doubling from $3.7 billion (2023) to $7.38 billion (2025), with projections reaching $103.6 billion by 2032. According to PwC's 2025 survey, 79% of organizations have adopted AI agents, with 88% of executives piloting or scaling autonomous agent systems.

🔑 Key Trends

1. Rise of Multi-Agent Systems
Instead of single AI systems trying to do everything, 2025 has introduced the "orchestra approach" where multiple specialized agents collaborate—one gathers research, another drafts reports, and a third reviews. Frameworks like CrewAI, AutoGen, and LangGraph are enabling this coordination across enterprise departments.

2. From Assistants to Autonomous Decision-Makers
AI agents are evolving from knowledge assistants to self-directed workers that can take initiative, make decisions, and complete multi-step tasks without constant human input. By 2029, 80% of customer service issues are expected to be resolved entirely by autonomous agents.

3. Model Context Protocol (MCP)
Anthropic's open standard provides a "USB-C for AI"—standardizing how language models connect with external systems, enabling structured multi-step workflows and access to real-time information.

4. Two-Speed Enterprise Landscape
A divide is emerging: companies with existing automation are racing ahead with agentic AI, while others watch from the sidelines. Among highly automated enterprises, 50% have either adopted or are preparing to adopt autonomous agents.

⚠️ Key Challenges

Integration with legacy systems (cited by ~60% of AI leaders)
Trust issues for high-stakes tasks like financial transactions
Enterprise readiness—organizations need to expose APIs and prepare infrastructure
Reliability concerns—agents can misinterpret instructions or fail on edge cases

💼 Impact

66% of adopters report measurable productivity gains
Early movers are cutting operational costs by up to 40%
75% of executives believe AI agents will reshape the workplace more than the internet did
87% agree AI agents augment roles rather than replace them

Sources:

What’s happening here:

query() creates a single-turn agent interaction (no conversation memory)
allowed_tools=["WebSearch"] gives Claude permission to search the web without asking for approval
The agent autonomously decides when to search, what queries to run, and how to synthesize results

Visualization utilities from utils.agent_visualizer: - print_activity() - Shows the agent’s actions in real-time (tool calls, thinking) - display_agent_response() - Renders the final response as a styled HTML card - visualize_conversation() - Creates a timeline view of the full conversation

That’s it! A functional research agent in just a few lines of code. The agent will search for relevant information, follow up on promising leads, and provide a synthesized summary with citations.

The query() function creates a stateless agent interaction. Each call is independent—no conversation memory, no context from previous queries. This makes it perfect for one-off research tasks where you need a quick answer without maintaining state.

How tool permissions work:

The allowed_tools=["WebSearch"] parameter gives Claude permission to search without asking for approval. This is critical for autonomous operation:

Allowed tools - Claude can use these freely (in this case, WebSearch)
Other tools - Available but require approval before use
Read-only tools - Tools like Read are always allowed by default
Disallowed tools - Add tools to disallowed_tools to remove them entirely from Claude’s context

When to use stateless queries:

One-off research questions where context doesn’t matter
Parallel processing of independent research tasks
Scenarios where you want fresh context for each query

When not to use stateless queries:

Multi-turn investigations that build on previous findings
Iterative refinement of research based on initial results
Complex analysis requiring sustained context

Let’s inspect what the agent actually did using the visualize_conversation helper:

from utils.agent_visualizer import visualize_conversation

visualize_conversation(messages)

🤖 Agent Conversation Timeline • claude-opus-4-6

⚙️ System

Initialized (4e8497a9...)

🔧 Tools

WebSearch: "AI agents trends 2025 latest d..."WebSearch: "autonomous AI agents enterpris..."WebSearch: "multi-agent AI systems trends ..."

🤖 Assistant

Latest Trends in AI Agents (2025) - Summary

🚀 Market Growth & Adoption

🔑 Key Trends

⚠️ Key Challenges

Integration with legacy systems (cited by ~60% of AI leaders)
Trust issues for high-stakes tasks like financial transactions
Enterprise readiness—organizations need to expose APIs and prepare infrastructure
Reliability concerns—agents can misinterpret instructions or fail on edge cases

💼 Impact

66% of adopters report measurable productivity gains
Early movers are cutting operational costs by up to 40%
75% of executives believe AI agents will reshape the workplace more than the internet did
87% agree AI agents augment roles rather than replace them

Sources:

✅ Complete

Turns: 4 Tokens: 4,145 Cost: $0.51 Duration: 51.1s

From Prototype to Production: Three Key Improvements

Our one-line research agent works, but it’s limited. Single queries without memory can’t handle iterative research (“find X, then analyze Y based on what you found”). Let’s explore three ways we can further improve our implementation.

1. Conversation Memory with ClaudeSDKClient: Stateless queries can’t build on previous findings. If you ask “What are the top AI startups?” then “How are they funded?”, the second query has no context about which startups you mean. We can use ClaudeSDKClient to maintain conversation history across multiple queries.

2. System Prompts for Specialized Behavior: Research domains often have specific requirements. Financial analysis needs different rigor than tech news summaries. Use the system prompt to encode your research standards, preferred sources, citation format, or output structure. See our agent prompting guide for research-specific examples.

3. Multimodal Research with the Read Tool: Real research isn’t just text. Market reports have charts, technical docs have diagrams, competitive analysis requires screenshot comparison. Enable the Read tool so Claude can analyze images, PDFs, and other visual content.

Let’s implement these three changes for our research agent.

from claude_agent_sdk import ClaudeSDKClient

# System prompt with citation requirements for research quality
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"""

messages = []
async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model=MODEL,
        cwd="research_agent",
        system_prompt=RESEARCH_SYSTEM_PROMPT,
        allowed_tools=["WebSearch", "Read"],
        max_buffer_size=10 * 1024 * 1024,  # Increase to 10MB for image handling
    )
) as research_agent:
    # First query: Analyze the chart image
    await research_agent.query("Analyze the chart in research_agent/projects_claude.png")
    async for msg in research_agent.receive_response():
        print_activity(msg)
        messages.append(msg)

    # Second query: Use web search to validate/contextualize the chart findings
    await research_agent.query(
        "Based on the chart analysis, search for recent news or data that validates or provides context for these findings. Include source URLs."
    )
    async for msg in research_agent.receive_response():
        print_activity(msg)
        messages.append(msg)

🤖 Using: Read()
✓ Tool completed
🤖 Thinking...
🤖 Using: Glob()
✓ Tool completed
🤖 Thinking...
🤖 Using: Read()
✓ Tool completed
🤖 Thinking...
🤖 Using: WebSearch()
🤖 Using: WebSearch()
🤖 Using: WebSearch()
🤖 Using: WebSearch()
✓ Tool completed
✓ Tool completed
✓ Tool completed
✓ Tool completed
🤖 Thinking...

🔧 Handling Large Responses and Buffer Limits

When working with images or large data, you may encounter buffer overflow errors:

Fatal error in message reader: Failed to decode JSON: JSON message exceeded maximum buffer size of 1048576 bytes

Why this happens: - The default max_buffer_size is 1MB (1,048,576 bytes) - Images are base64-encoded in messages, significantly increasing size - The chart image (~200KB on disk) becomes ~270KB+ when base64-encoded, plus message overhead

Solution: Set max_buffer_size in ClaudeAgentOptions to a higher value (e.g., 10MB) when working with images or large tool outputs.

Best practices: - Set buffer size based on your use case: 10MB for typical multimodal work, higher for large document processing - Consider if you really need to pass full images - sometimes descriptions or smaller thumbnails suffice - Monitor for buffer errors and adjust accordingly - Include citation requirements in your system prompt to ensure verifiable research outputs

What’s happening here:

This example combines all three improvements: conversation memory, citation-aware system prompt, and multimodal analysis.

Key components:

Component	Purpose
`ClaudeSDKClient`	Maintains conversation state across multiple queries
`RESEARCH_SYSTEM_PROMPT`	Enforces citation formatting and source URLs
`allowed_tools=["WebSearch", "Read"]`	Enables web search and image/document analysis
`max_buffer_size=10MB`	Handles base64-encoded images without overflow

Execution flow:

First query - Analyzes the chart image using the Read tool
First response loop - Collects all messages until the agent completes
Second query - Searches the web to validate/contextualize the chart findings
Context inheritance - The second query remembers the chart analysis from the first

Why ClaudeSDKClient vs query():

The async with ClaudeSDKClient() context manager maintains conversation state. Each receive_response() call builds on previous context. This differs from query() which creates independent, stateless sessions.

visualize_conversation(messages)

🤖 Agent Conversation Timeline • claude-opus-4-6

⚙️ System

Initialized (9d494ab0...)

🔧 Tools

Read: projects_claude.png

🤖 Assistant

Let me search for the file in different locations:

🔧 Tools

Glob

🤖 Assistant

Found it. Let me read the image:

🔧 Tools

Read: projects_claude.png

🤖 Assistant

Analysis of the Chart: Types of Projects in Claude.ai and Claude Code

This is a dumbbell chart (also called a connected dot plot) that compares the prevalence of different project types between two Anthropic products: Claude.ai (blue dots) and Claude Code (orange dots).

Key Findings

1. Personal Projects Lead Both Platforms

Claude Code: 36.0%
Claude.ai: 30.2%
This is the most common use case for both platforms, with Claude Code having a slight edge (~6% higher).

2. Startup Work Shows the Largest Gap

Claude Code: 32.9%
Claude.ai: 13.1%
This represents the biggest difference between the two platforms (~20% gap), indicating Claude Code is heavily favored for startup development work.

3. Enterprise Work is Relatively Balanced

Claude.ai: 25.9%
Claude Code: 23.8%
Both platforms see similar usage for enterprise work, with Claude.ai slightly ahead (~2% difference).

4. Learning & Academic Use Favors Claude.ai

Tutorial or Learning: Claude.ai (12.2%) vs Claude Code (0.7%)
Academic Research: Claude.ai (11.9%) vs Claude Code (2.2%)
Coursework: Claude.ai (4.9%) vs Claude Code (0.4%)
These categories show Claude.ai is significantly more popular for educational purposes, likely due to its conversational interface being more accessible for learning.

5. Open Source Projects are Low for Both

Claude Code: 4.0%
Claude.ai: 1.8%
Neither platform sees heavy use for open source contributions, though Claude Code is used slightly more.

Insights & Interpretation

Pattern	Implication
Claude Code dominates Startup Work	Developers building products at startups prefer the code-focused interface for rapid development
Claude.ai leads in educational contexts	The conversational nature of Claude.ai makes it more approachable for learning, research, and coursework
Personal Projects are universal	Both platforms serve individual developers working on side projects equally well
Enterprise usage is balanced	Both products have found their place in professional enterprise environments

Summary

The chart reveals clear product differentiation:
- Claude Code is preferred for active software development (startups, personal coding projects, open source)
- Claude.ai excels in knowledge work and learning (tutorials, academic research, coursework)

This aligns with the nature of each product—Claude Code is a development tool while Claude.ai is a general-purpose AI assistant with a broader conversational interface.

✅ Complete

Turns: 4 Tokens: 887 Cost: $0.07 Duration: 27.6s

⚙️ System

Initialized (9d494ab0...)

🔧 Tools

WebSearch: "Claude Code developer adoption..."WebSearch: "Claude AI education academic r..."WebSearch: "Anthropic Claude Code vs Claud..."WebSearch: "AI coding assistants startup d..."

🤖 Assistant

Validation & Context for Chart Findings

Based on my research, here's how recent news and data validate or provide context for the chart analysis:

1. ✅ Startup Dominance in Claude Code - VALIDATED

The chart showed Claude Code usage for Startup Work at 32.9% vs only 13.1% for Claude.ai—the largest gap in the data. Recent news strongly confirms this:

"Startups are the main early adopters of Claude Code, suggesting that smaller, agile businesses are leveraging this AI tool to gain a technological advantage." - Blockchain News

YC Startups as Case Studies:
- HumanLayer (F24) - Built their entire platform with Claude Code
- Ambral (W25) - Scaling AI-powered account management with sub-agent workflows
- Vulcan Technologies (S25) - Using Claude Code for regulatory complexity

As noted by Anthropic's blog: "Founders can now ship products directly from the terminal, compressing development cycles from weeks to hours."

2. ✅ Educational Use Favors Claude.ai - VALIDATED

The chart showed Claude.ai leading significantly in:
- Tutorial or Learning: 12.2% (vs 0.7% for Claude Code)
- Academic Research: 11.9% (vs 2.2%)
- Coursework: 4.9% (vs 0.4%)

This aligns perfectly with Anthropic's dedicated education initiatives:

Anthropic launched "Claude for Education" with features like "Learning Mode" that uses Socratic questioning rather than giving direct answers. - VentureBeat

Key Statistics from Anthropic's Education Report:
- 39.3% of student conversations involve creating and improving educational content
- 33.5% involve getting technical explanations for academic assignments
- 57% of higher ed instructor chats involved developing curricula
- 13% were conducting academic research

Early adopters include Northeastern University (50,000+ students across 13 campuses), London School of Economics, and Champlain College. - Anthropic Education Report

3. ✅ Coding/Development Dominance - VALIDATED

The chart showed Personal Projects and Startup Work (both development-heavy) as top uses for Claude Code (36% and 32.9%).

Anthropic's own research confirms:

"About 44% of API traffic involved coding, compared with 36% on Claude.ai." - Anthropic Economic Index

"Software development remains Claude's most common use case, making up more than a third of activity globally." - eWeek

4. ✅ Product Differentiation (Claude Code vs Claude.ai) - VALIDATED

The chart's overall pattern showing Claude Code for development and Claude.ai for knowledge work is confirmed by Fortune:

"ChatGPT is emerging increasingly as a personal or exploratory tool... while Claude is a more work-focused productivity tool, used heavily for coding, research, and business automation." - Fortune

Automation patterns differ by platform:
- 77% of API tasks are automated (full task delegation)
- ~50% of Claude.ai tasks are automated (more collaborative)

5. 📊 Broader AI Coding Assistant Context

The chart's findings fit into the larger industry trend:

Metric	2025 Data
AI-generated/assisted code	41% of all code globally
Developers using AI coding assistants	82% daily or weekly
Market size projection	$30.1 billion by 2032
Google's AI-assisted code	25%

Source: AI Coding Assistant Statistics

6. ⚠️ Enterprise Work Balance - PARTIALLY EXPLAINED

The chart showed Enterprise Work relatively balanced (Claude.ai: 25.9%, Claude Code: 23.8%). This makes sense given:

70-75% of Anthropic's revenue comes from enterprise API consumption
Enterprises use both products depending on use case
Security features like FedRAMP High certification drive enterprise adoption of both platforms

Summary

The chart's findings are strongly validated by recent data:

Chart Finding	Validation Status
Startups prefer Claude Code (32.9% vs 13.1%)	✅ Confirmed by Anthropic & YC case studies
Education favors Claude.ai (12.2% vs 0.7%)	✅ Confirmed by Anthropic Education Report
Personal projects lead both platforms	✅ Confirmed by usage statistics
Claude Code = development tool	✅ Confirmed (44% API traffic is coding)
Claude.ai = knowledge/learning tool	✅ Confirmed by education initiatives

Sources

✅ Complete

Turns: 5 Tokens: 2,152 Cost: $0.76 Duration: 73.0s

Building for Production

Jupyter notebooks are great for learning, but production systems need reusable modules. We’ve packaged the research agent into research_agent/agent.py with a clean interface:

Core functions:

print_activity() - Shows what the agent is doing in real-time (imported from shared utilities)
get_activity_text() - Extract activity text for custom handlers, such as logging or monitoring
send_query() - Main entry point for research queries with built-in activity display

Built-in best practices:

The module includes the RESEARCH_SYSTEM_PROMPT which ensures: - Source URLs are always included as citations - Citations are formatted as markdown links for clean rendering - A “Sources:” section groups all references

Display control:

The send_query() function has a display_result parameter (default: True): - display_result=True - Renders a styled HTML card in Jupyter notebooks - display_result=False - Returns only the text result for programmatic use

This agent can now be used in any Python script!

For independent questions where conversation context doesn’t matter.

The module automatically handles: - Activity display during execution - Context reset for new conversations - Styled HTML rendering of the final response

from research_agent.agent import send_query

# The module handles activity display, context reset, and result visualization internally
result = await send_query("What is the Claude Code SDK? Only do one websearch and be concise")

🤖 Using: WebSearch()
✓ Tool completed
🤖 Thinking...

Agent Response

Claude Code SDK

The Claude Code SDK (now renamed to Claude Agent SDK) is a toolkit from Anthropic that allows developers to build AI agents using the same infrastructure that powers Claude Code.

Key capabilities:
- Context management - Automatic compaction to prevent running out of context
- Rich tool ecosystem - File operations, code execution, web search, MCP extensibility
- Fine-grained permissions - Control over agent capabilities
- Production features - Error handling, session management, monitoring

Available in:
- TypeScript (@anthropic-ai/claude-code)
- Python (pip install claude-code-sdk)
- Command line

It enables building agents for coding automation, customer support, personal assistants, and more—all using the same core systems that power Claude Code.

Sources:
- Agent SDK overview - Claude Docs
- Building agents with the Claude Agent SDK
- Anthropic Releases Claude Code SDK - InfoQ

Now we test out a multi-turn conversation that reuses the same conversation.

Multi-turn conversations work seamlessly—just pass continue_conversation=True:

result1 = await send_query("What is Anthropic? Only do one websearch and be concise")

🤖 Using: WebSearch()
✓ Tool completed
🤖 Thinking...

Agent Response

Anthropic is an American AI safety company founded in 2021 by former OpenAI executives, including siblings Dario and Daniela Amodei. The company builds Claude, a family of large language models, with a focus on creating reliable, interpretable, and safe AI systems. Anthropic is valued at approximately $183 billion and has received major investments from Amazon, Google, Microsoft, and NVIDIA. Its Claude Code product recently reached $1 billion in run-rate revenue.

Sources:
- Anthropic - Wikipedia
- Anthropic Homepage
- What's Anthropic AI? - Voiceflow

# Continue the conversation to dig deeper by setting continue_conversation=True
result2 = await send_query(
    "What are some of their products?",
    continue_conversation=True,
)

🤖 Thinking...

Agent Response

Based on my previous search results, here are Anthropic's main products:

Claude - Their flagship AI assistant and family of large language models, which incorporates "Constitutional AI" for safety. Named after mathematician Claude Shannon.
Claude Code - A developer tool that recently reached $1 billion in run-rate revenue just six months after public launch.
Bun - A JavaScript runtime that Anthropic recently acquired to accelerate Claude Code's capabilities.

Anthropic offers Claude through their website, API access for developers, and enterprise solutions.

Sources:
- Anthropic Homepage
- Anthropic acquires Bun as Claude Code reaches $1B milestone

Conclusion

What You Built

In this cookbook, you built three progressively sophisticated research agents:

Stateless research agent - One-line queries for independent research tasks
Stateful agent with memory - Multi-turn investigations that build on previous findings
Production module - Reusable research functions for integration into applications

Key Takeaways

When to use stateless queries (query()):

Independent research questions
Parallel processing of unrelated tasks
Scenarios requiring fresh context each time

When to use stateful agents (ClaudeSDKClient):

Multi-turn investigations building on previous findings
Iterative refinement of research
Complex analysis requiring sustained context

Research agents excel when information isn’t self-contained and the optimal workflow emerges during exploration—competitive analysis, technical troubleshooting, literature reviews, and investigative journalism all fit this pattern.

Next Steps

This foundation in autonomous research prepares you for enterprise-grade multi-agent systems. In the next notebook, you’ll learn to:

Orchestrate specialized subagents under a coordinating agent Implement governance through hooks and custom commands Adapt output styles for different stakeholders (executives vs. technical teams)

Next: 01_The_chief_of_staff_agent.ipynb - From single agents to multi-agent orchestration.