Quickstart

This guide walks you through creating your first deep agent with planning, file system tools, and subagent capabilities. You’ll build a research agent that can conduct research and write reports.

Prerequisites

Before you begin, make sure you have an API key from a model provider (e.g., Anthropic, OpenAI).

Deep agents require a model that supports tool calling. See customization for how to configure your model.

Step 1: Install dependencies

pip install deepagents tavily-python

uv init
uv add deepagents tavily-python
uv sync

This guide uses Tavily as an example search provider, but you can substitute any search API (e.g., DuckDuckGo, SerpAPI, Brave Search).

Step 2: Set up your API keys

export ANTHROPIC_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

Step 3: Create a search tool

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

Step 4: Create a deep agent

# System prompt to steer the agent to be an expert researcher
research_instructions = """You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## `internet_search`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
"""

agent = create_deep_agent(
    tools=[internet_search],
    system_prompt=research_instructions
)

Step 5: Run the agent

result = agent.invoke({"messages": [{"role": "user", "content": "What is langgraph?"}]})

# Print the agent's response
print(result["messages"][-1].content)

How does it work?

Your deep agent automatically:

Plans its approach using the built-in write_todos tool to break down the research task.
Conducts research by calling the internet_search tool to gather information.
Manages context by using file system tools (write_file, read_file) to offload large search results.
Spawns subagents as needed to delegate complex subtasks to specialized subagents.
Synthesizes a report to compile findings into a coherent response.

Examples

For agents, patterns, and applications you can build with Deep Agents, see Examples.

Next steps

Now that you’ve built your first deep agent:

Customize your agent: Learn about customization options, including custom system prompts, tools, and subagents.
Understand middleware: Dive into the middleware architecture that powers deep agents.
Add long-term memory: Enable persistent memory across conversations.
Deploy to production: Learn about deployment options for LangGraph applications.

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Get started

Core capabilities

Command line interface

Prerequisites

Step 1: Install dependencies

Step 2: Set up your API keys

Step 3: Create a search tool

Step 4: Create a deep agent

Step 5: Run the agent

How does it work?

Examples

Next steps

​Prerequisites

​Step 1: Install dependencies

​Step 2: Set up your API keys

​Step 3: Create a search tool

​Step 4: Create a deep agent

​Step 5: Run the agent

​How does it work?

​Examples

​Next steps

Prerequisites

Step 1: Install dependencies

Step 2: Set up your API keys

Step 3: Create a search tool

Step 4: Create a deep agent

Step 5: Run the agent

How does it work?

Examples

Next steps