Quickstart

Build your first deep agent in minutes

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

Using an AI coding assistant?

• Install the LangChain Docs MCP server to give your agent access to up-to-date LangChain documentation and examples.
• Install LangChain Skills to improve your agent’s performance on LangChain ecosystem tasks.

Prerequisites

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

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

Step 1: Install dependencies

pip

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

Google

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

OpenAI

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

Anthropic

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

OpenRouter

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

Fireworks

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

Baseten

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

Ollama

# Local: Ollama must be running on your machine
# Cloud: Set your Ollama API key for hosted inference
export OLLAMA_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

Other

# Set the API key for your provider
export <PROVIDER>_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

Deep Agents work with any LangChain chat model. Set the API key for your provider.

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

Pass a model string in provider:model format, or an initialized model instance. See supported models for all providers and suggested models for tested recommendations.

Google

# 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(
    model="google_genai:gemini-3.5-flash",
    tools=[internet_search],
    system_prompt=research_instructions,
)

# 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(
    model="openai:gpt-5.5",
    tools=[internet_search],
    system_prompt=research_instructions,
)

# 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(
    model="anthropic:claude-sonnet-4-6",
    tools=[internet_search],
    system_prompt=research_instructions,
)

# 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(
    model="openrouter:z-ai/glm-5.2",
    tools=[internet_search],
    system_prompt=research_instructions,
)

# 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(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    tools=[internet_search],
    system_prompt=research_instructions,
)

# 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(
    model="baseten:zai-org/GLM-5.2",
    tools=[internet_search],
    system_prompt=research_instructions,
)

# 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(
    model="ollama:north-mini-code-1.0",
    tools=[internet_search],
    system_prompt=research_instructions,
)

Step 5: Set up LangSmith tracing

LangSmith provides you with visibility into your agent’s execution, allowing you to view planning steps, tool calls, subagent delegation, and LLM responses.

Sign up at smith.langchain.com, create an API key, and set these environment variables:

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

Step 6: 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:

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

Examples

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

Streaming

Deep Agents have built-in streaming for real-time updates from agent execution using LangGraph. This allows you to observe output progressively and review and debug agent and subagent work, such as tool calls, tool results, and LLM responses.

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.
• Add long-term memory: Enable persistent memory across conversations.
• Deploy to production: Use Managed Deep Agents to create, run, and operate deep agents in LangSmith.
• Test and evaluate: Use LangSmith evaluation to run automated tests and measure your agent’s performance against a dataset.

---

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

Edit this page on GitHub or file an issue.