{ "cells": [ { "cell_type": "markdown", "id": "0d4a77a4", "metadata": {}, "source": [ "# Building a One-Liner Research Agent\n", "\n", "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.\n", "\n", "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.\n", "\n", "## By the end of this cookbook, you'll be able to:\n", "\n", "- Build a research agent that autonomously searches and synthesizes information with a few lines of code\n", "\n", "This foundation applies to any task where the information needed isn't available upfront: competitive analysis, technical troubleshooting, investment research, or literature reviews.\n", "\n", "# Why Research Agents?\n", "\n", "Research is an ideal agentic use case for two reasons:\n", "\n", "1. **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.\n", "2. **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.\n", "\n", "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.\n", "\n", "Note: You can also view the full list of [Claude Code's built-in tools](https://docs.claude.com/en/docs/claude-code/settings#tools-available-to-claude)" ] }, { "cell_type": "markdown", "id": "301fb086", "metadata": {}, "source": [ "# Prerequisites\n", "\n", "Before following this guide, ensure you have:\n", "\n", "**Required Knowledge**\n", "\n", "* Python fundamentals - comfortable with async/await, functions, and basic data structures\n", "* Basic understanding of agentic patterns - we recommend reading [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) first if you're new to agents\n", "\n", "**Required Tools**\n", "\n", "* Python 3.11 or higher\n", "* Anthropic API key [(get one here)](https://console.anthropic.com)\n", "\n", "**Recommended:**\n", "* Familiarity with the Claude Agent SDK concepts\n", "* Understanding of tool use patterns in LLMs\n", "\n", "\n", "## Setup\n", "\n", "First, install the required dependencies:" ] }, { "cell_type": "code", "execution_count": null, "id": "ab9830f9", "metadata": {}, "outputs": [], "source": "%%capture\n%pip install -U claude-agent-sdk python-dotenv" }, { "cell_type": "markdown", "id": "d88272cf", "metadata": {}, "source": [ "Note: Ensure your .env file contains:\n", "\n", "```bash\n", "ANTHROPIC_API_KEY=your_key_here\n", "```\n", "\n", "Load your environment variables and configure the client:" ] }, { "cell_type": "code", "execution_count": 2, "id": "c41abcdf", "metadata": {}, "outputs": [], "source": [ "from dotenv import load_dotenv\n", "\n", "load_dotenv()\n", "\n", "MODEL = \"claude-opus-4-6\"" ] }, { "cell_type": "markdown", "id": "041415b8", "metadata": {}, "source": [ "## Building Your First Research Agent\n", "\n", "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.\n", "\n", "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." ] }, { "cell_type": "code", "execution_count": 3, "id": "b00890fb", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "🤖 Using: WebSearch()\n", "🤖 Using: WebSearch()\n", "🤖 Using: WebSearch()\n", "✓ Tool completed\n", "✓ Tool completed\n", "✓ Tool completed\n", "🤖 Thinking...\n" ] } ], "source": [ "from utils.agent_visualizer import (\n", " display_agent_response,\n", " print_activity,\n", ")\n", "\n", "from claude_agent_sdk import ClaudeAgentOptions, query\n", "\n", "messages = []\n", "async for msg in query(\n", " prompt=\"Research the latest trends in AI agents and give me a brief summary and relevant citiations links.\",\n", " options=ClaudeAgentOptions(model=MODEL, allowed_tools=[\"WebSearch\"]),\n", "):\n", " print_activity(msg)\n", " messages.append(msg)" ] }, { "cell_type": "code", "execution_count": 4, "id": "e4556936", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "
Agent Response

Latest Trends in AI Agents (2025) - Summary

\n", "

🚀 Market Growth & Adoption

\n", "

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.

\n", "

🔑 Key Trends

\n", "

1. Rise of Multi-Agent Systems
\n", "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.

\n", "

2. From Assistants to Autonomous Decision-Makers
\n", "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.

\n", "

3. Model Context Protocol (MCP)
\n", "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.

\n", "

4. Two-Speed Enterprise Landscape
\n", "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.

\n", "

⚠️ Key Challenges

\n", "\n", "

đź’Ľ Impact

\n", "\n", "
\n", "

Sources:

\n", "
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "display_agent_response(messages)" ] }, { "cell_type": "markdown", "id": "b965c2ee", "metadata": {}, "source": [ "## What's happening here:\n", "\n", "- `query()` creates a single-turn agent interaction (no conversation memory)\n", "- `allowed_tools=[\"WebSearch\"]` gives Claude permission to search the web without asking for approval\n", "- The agent autonomously decides when to search, what queries to run, and how to synthesize results\n", "\n", "**Visualization utilities from `utils.agent_visualizer`:**\n", "- `print_activity()` - Shows the agent's actions in real-time (tool calls, thinking)\n", "- `display_agent_response()` - Renders the final response as a styled HTML card\n", "- `visualize_conversation()` - Creates a timeline view of the full conversation\n", "\n", "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." ] }, { "cell_type": "markdown", "id": "6b888772", "metadata": {}, "source": [ "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.\n", "\n", "**How tool permissions work:**\n", "\n", "The `allowed_tools=[\"WebSearch\"]` parameter gives Claude permission to search without asking for approval. This is critical for autonomous operation:\n", "\n", "- `Allowed tools` - Claude can use these freely (in this case, WebSearch)\n", "- `Other tools` - Available but require approval before use\n", "- `Read-only tools` - Tools like Read are always allowed by default\n", "- `Disallowed tools` - Add tools to disallowed_tools to remove them entirely from Claude's context\n", "\n", "**When to use stateless queries:**\n", "\n", "- One-off research questions where context doesn't matter\n", "- Parallel processing of independent research tasks\n", "- Scenarios where you want fresh context for each query\n", "\n", "**When not to use stateless queries:**\n", "\n", "- Multi-turn investigations that build on previous findings\n", "- Iterative refinement of research based on initial results\n", "- Complex analysis requiring sustained context\n", "\n", "Let's inspect what the agent actually did using the visualize_conversation helper:" ] }, { "cell_type": "code", "execution_count": 5, "id": "1d7c6d90", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", "\n", "\n", "
\n", "
🤖 Agent Conversation Timeline • claude-opus-4-6
\n", "
\n", "
⚙️ 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

\n", "

🚀 Market Growth & Adoption

\n", "

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.

\n", "

🔑 Key Trends

\n", "

1. Rise of Multi-Agent Systems
\n", "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.

\n", "

2. From Assistants to Autonomous Decision-Makers
\n", "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.

\n", "

3. Model Context Protocol (MCP)
\n", "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.

\n", "

4. Two-Speed Enterprise Landscape
\n", "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.

\n", "

⚠️ Key Challenges

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

đź’Ľ Impact

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

Sources:

\n", "
âś… Complete
Turns: 4 Tokens: 4,145 Cost: $0.51 Duration: 51.1s
\n", "
\n", "
\n", " " ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from utils.agent_visualizer import visualize_conversation\n", "\n", "visualize_conversation(messages)" ] }, { "cell_type": "markdown", "id": "22426729", "metadata": {}, "source": [ "## From Prototype to Production: Three Key Improvements\n", "\n", "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.\n", "\n", "**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.\n", "\n", "\n", "**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](https://github.com/anthropics/anthropic-cookbook/tree/main/patterns/agents/prompts) for research-specific examples.\n", "\n", "**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.\n", "\n", "Let's implement these three changes for our research agent." ] }, { "cell_type": "code", "execution_count": 6, "id": "fa4c4d8f", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "🤖 Using: Read()\n", "✓ Tool completed\n", "🤖 Thinking...\n", "🤖 Using: Glob()\n", "✓ Tool completed\n", "🤖 Thinking...\n", "🤖 Using: Read()\n", "✓ Tool completed\n", "🤖 Thinking...\n", "🤖 Using: WebSearch()\n", "🤖 Using: WebSearch()\n", "🤖 Using: WebSearch()\n", "🤖 Using: WebSearch()\n", "✓ Tool completed\n", "✓ Tool completed\n", "✓ Tool completed\n", "✓ Tool completed\n", "🤖 Thinking...\n" ] } ], "source": [ "from claude_agent_sdk import ClaudeSDKClient\n", "\n", "# System prompt with citation requirements for research quality\n", "RESEARCH_SYSTEM_PROMPT = \"\"\"You are a research agent specialized in AI.\n", "\n", "When providing research findings:\n", "- Always include source URLs as citations\n", "- Format citations as markdown links: [Source Title](URL)\n", "- Group sources in a \"Sources:\" section at the end of your response\"\"\"\n", "\n", "messages = []\n", "async with ClaudeSDKClient(\n", " options=ClaudeAgentOptions(\n", " model=MODEL,\n", " cwd=\"research_agent\",\n", " system_prompt=RESEARCH_SYSTEM_PROMPT,\n", " allowed_tools=[\"WebSearch\", \"Read\"],\n", " max_buffer_size=10 * 1024 * 1024, # Increase to 10MB for image handling\n", " )\n", ") as research_agent:\n", " # First query: Analyze the chart image\n", " await research_agent.query(\"Analyze the chart in research_agent/projects_claude.png\")\n", " async for msg in research_agent.receive_response():\n", " print_activity(msg)\n", " messages.append(msg)\n", "\n", " # Second query: Use web search to validate/contextualize the chart findings\n", " await research_agent.query(\n", " \"Based on the chart analysis, search for recent news or data that validates or provides context for these findings. Include source URLs.\"\n", " )\n", " async for msg in research_agent.receive_response():\n", " print_activity(msg)\n", " messages.append(msg)" ] }, { "cell_type": "markdown", "id": "i4blqsetg8", "metadata": {}, "source": [ "### 🔧 Handling Large Responses and Buffer Limits\n", "\n", "When working with images or large data, you may encounter buffer overflow errors:\n", "\n", "```\n", "Fatal error in message reader: Failed to decode JSON: JSON message exceeded maximum buffer size of 1048576 bytes\n", "```\n", "\n", "**Why this happens:**\n", "- The default `max_buffer_size` is 1MB (1,048,576 bytes)\n", "- Images are base64-encoded in messages, significantly increasing size\n", "- The chart image (~200KB on disk) becomes ~270KB+ when base64-encoded, plus message overhead\n", "\n", "**Solution:**\n", "Set `max_buffer_size` in `ClaudeAgentOptions` to a higher value (e.g., 10MB) when working with images or large tool outputs.\n", "\n", "**Best practices:**\n", "- Set buffer size based on your use case: 10MB for typical multimodal work, higher for large document processing\n", "- Consider if you really need to pass full images - sometimes descriptions or smaller thumbnails suffice\n", "- Monitor for buffer errors and adjust accordingly\n", "- Include citation requirements in your system prompt to ensure verifiable research outputs" ] }, { "cell_type": "markdown", "id": "6eb4ed21", "metadata": {}, "source": [ "## What's happening here:\n", "\n", "This example combines all three improvements: conversation memory, citation-aware system prompt, and multimodal analysis.\n", "\n", "**Key components:**\n", "\n", "| Component | Purpose |\n", "|-----------|---------|\n", "| `ClaudeSDKClient` | Maintains conversation state across multiple queries |\n", "| `RESEARCH_SYSTEM_PROMPT` | Enforces citation formatting and source URLs |\n", "| `allowed_tools=[\"WebSearch\", \"Read\"]` | Enables web search and image/document analysis |\n", "| `max_buffer_size=10MB` | Handles base64-encoded images without overflow |\n", "\n", "**Execution flow:**\n", "\n", "1. **First query** - Analyzes the chart image using the `Read` tool\n", "2. **First response loop** - Collects all messages until the agent completes\n", "3. **Second query** - Searches the web to validate/contextualize the chart findings\n", "4. **Context inheritance** - The second query remembers the chart analysis from the first\n", "\n", "**Why `ClaudeSDKClient` vs `query()`:**\n", "\n", "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." ] }, { "cell_type": "code", "execution_count": 7, "id": "7971eae4-3ff1-48d8-99ef-fecca7332163", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", " \n", "\n", "\n", "
\n", "
🤖 Agent Conversation Timeline • claude-opus-4-6
\n", "
\n", "
⚙️ 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

\n", "

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).

\n", "

Key Findings

\n", "

1. Personal Projects Lead Both Platforms

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

2. Startup Work Shows the Largest Gap

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

3. Enterprise Work is Relatively Balanced

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

4. Learning & Academic Use Favors Claude.ai

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

5. Open Source Projects are Low for Both

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

Insights & Interpretation

\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
PatternImplication
Claude Code dominates Startup WorkDevelopers building products at startups prefer the code-focused interface for rapid development
Claude.ai leads in educational contextsThe conversational nature of Claude.ai makes it more approachable for learning, research, and coursework
Personal Projects are universalBoth platforms serve individual developers working on side projects equally well
Enterprise usage is balancedBoth products have found their place in professional enterprise environments
\n", "

Summary

\n", "

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

\n", "

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

\n", "

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

\n", "
\n", "

1. âś… Startup Dominance in Claude Code - VALIDATED

\n", "

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:

\n", "
\n", "

\"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

\n", "
\n", "

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

\n", "

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

\n", "
\n", "

2. âś… Educational Use Favors Claude.ai - VALIDATED

\n", "

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

\n", "

This aligns perfectly with Anthropic's dedicated education initiatives:

\n", "
\n", "

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

\n", "
\n", "

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

\n", "

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

\n", "
\n", "

3. âś… Coding/Development Dominance - VALIDATED

\n", "

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

\n", "

Anthropic's own research confirms:

\n", "
\n", "

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

\n", "

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

\n", "
\n", "
\n", "

4. âś… Product Differentiation (Claude Code vs Claude.ai) - VALIDATED

\n", "

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

\n", "
\n", "

\"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

\n", "
\n", "

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

\n", "
\n", "

5. đź“Š Broader AI Coding Assistant Context

\n", "

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

\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Metric2025 Data
AI-generated/assisted code41% of all code globally
Developers using AI coding assistants82% daily or weekly
Market size projection$30.1 billion by 2032
Google's AI-assisted code25%
\n", "

Source: AI Coding Assistant Statistics

\n", "
\n", "

6. ⚠️ Enterprise Work Balance - PARTIALLY EXPLAINED

\n", "

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

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

Summary

\n", "

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

\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Chart FindingValidation 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
\n", "
\n", "

Sources

\n", "
âś… Complete
Turns: 5 Tokens: 2,152 Cost: $0.76 Duration: 73.0s
\n", "
\n", "
\n", " " ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "visualize_conversation(messages)" ] }, { "cell_type": "markdown", "id": "38256581", "metadata": {}, "source": [ "## Building for Production\n", "\n", "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:\n", "\n", "### Core functions:\n", "\n", "- `print_activity()` - Shows what the agent is doing in real-time (imported from shared utilities)\n", "- `get_activity_text()` - Extract activity text for custom handlers, such as logging or monitoring\n", "- `send_query()` - Main entry point for research queries with built-in activity display\n", "\n", "### Built-in best practices:\n", "\n", "The module includes the `RESEARCH_SYSTEM_PROMPT` which ensures:\n", "- Source URLs are always included as citations\n", "- Citations are formatted as markdown links for clean rendering\n", "- A \"Sources:\" section groups all references\n", "\n", "### Display control:\n", "\n", "The `send_query()` function has a `display_result` parameter (default: `True`):\n", "- `display_result=True` - Renders a styled HTML card in Jupyter notebooks\n", "- `display_result=False` - Returns only the text result for programmatic use\n", "\n", "This agent can now be used in any Python script!" ] }, { "cell_type": "markdown", "id": "e220b5c7-463b-4171-b687-b1ec974958de", "metadata": {}, "source": [ "For independent questions where conversation context doesn't matter.\n", "\n", "The module automatically handles:\n", "- Activity display during execution\n", "- Context reset for new conversations\n", "- Styled HTML rendering of the final response" ] }, { "cell_type": "code", "execution_count": 8, "id": "3c2ca449-7a36-4b67-af47-fdb68fb3e36b", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "🤖 Using: WebSearch()\n", "✓ Tool completed\n", "🤖 Thinking...\n" ] }, { "data": { "text/html": [ "\n", "\n", "
Agent Response

Claude Code SDK

\n", "

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.

\n", "

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

\n", "

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

\n", "

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

\n", "
\n", "

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

" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from research_agent.agent import send_query\n", "\n", "# The module handles activity display, context reset, and result visualization internally\n", "result = await send_query(\"What is the Claude Code SDK? Only do one websearch and be concise\")" ] }, { "cell_type": "markdown", "id": "466155ec-9f54-49d4-83cb-00032b077147", "metadata": {}, "source": [ "Now we test out a multi-turn conversation that reuses the same conversation.\n", "\n", "Multi-turn conversations work seamlessly—just pass `continue_conversation=True`:" ] }, { "cell_type": "code", "execution_count": 9, "id": "38ba1eda", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "🤖 Using: WebSearch()\n", "✓ Tool completed\n", "🤖 Thinking...\n" ] }, { "data": { "text/html": [ "\n", "\n", "
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.

\n", "

Sources:
\n", "- Anthropic - Wikipedia
\n", "- Anthropic Homepage
\n", "- What's Anthropic AI? - Voiceflow

" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "result1 = await send_query(\"What is Anthropic? Only do one websearch and be concise\")" ] }, { "cell_type": "code", "execution_count": 10, "id": "36931a9e", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "🤖 Thinking...\n" ] }, { "data": { "text/html": [ "\n", "\n", "
Agent Response

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

\n", "
    \n", "
  1. \n", "

    Claude - Their flagship AI assistant and family of large language models, which incorporates \"Constitutional AI\" for safety. Named after mathematician Claude Shannon.

    \n", "
    2. \n", "
  2. \n", "

    Claude Code - A developer tool that recently reached $1 billion in run-rate revenue just six months after public launch.

    \n", "
    3. \n", "
  3. \n", "

    Bun - A JavaScript runtime that Anthropic recently acquired to accelerate Claude Code's capabilities.

    \n", "
    4. \n", "
\n", "

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

\n", "

Sources:
\n", "- Anthropic Homepage
\n", "- Anthropic acquires Bun as Claude Code reaches $1B milestone

" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Continue the conversation to dig deeper by setting continue_conversation=True\n", "result2 = await send_query(\n", " \"What are some of their products?\",\n", " continue_conversation=True,\n", ")" ] }, { "cell_type": "markdown", "id": "5344587c", "metadata": {}, "source": [ "## Conclusion\n", "\n", "### What You Built\n", "\n", "In this cookbook, you built three progressively sophisticated research agents:\n", "\n", "- Stateless research agent - One-line queries for independent research tasks\n", "- Stateful agent with memory - Multi-turn investigations that build on previous findings\n", "- Production module - Reusable research functions for integration into applications\n", "\n", "### Key Takeaways\n", "\n", "**When to use stateless queries (query()):**\n", "\n", "- Independent research questions\n", "- Parallel processing of unrelated tasks\n", "- Scenarios requiring fresh context each time\n", "\n", "**When to use stateful agents (ClaudeSDKClient):**\n", "\n", "- Multi-turn investigations building on previous findings\n", "- Iterative refinement of research\n", "- Complex analysis requiring sustained context\n", "\n", "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.\n", "\n", "### Next Steps\n", "\n", "This foundation in autonomous research prepares you for enterprise-grade multi-agent systems. In the next notebook, you'll learn to:\n", "\n", "Orchestrate specialized subagents under a coordinating agent\n", "Implement governance through hooks and custom commands\n", "Adapt output styles for different stakeholders (executives vs. technical teams)\n", "\n", "Next: [01_The_chief_of_staff_agent.ipynb](01_The_chief_of_staff_agent.ipynb) - From single agents to multi-agent orchestration." ] } ], "metadata": { "kernelspec": { "display_name": "cc-sdk-tutorial", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.9" } }, "nbformat": 4, "nbformat_minor": 5 }