DOCSEARCHbyAlgolia
Submit Docs

Deep Agents Quickstarts

repository·main·Indexed 19 days ago

https://github.com/langchain-ai/deepagents-quickstarts

A collection of quickstarts for building deep agents using the deepagents package, featuring a deep research agent example (v0.1.0). It provides guidance on using create_deep_agent to initialize agents with custom tools, task-specific instructions, and sub-agents for context isolation. The documentation covers environment setup with uv, integration with LangGraph Server and deep-agents-ui, and support for models such as Claude and Gemini.

Tokens
3K
Snippets
10
Records
12
Agent score
64%

What's inside deepagents-quickstarts

  1. Modify Deep Research Instructions

    main

    The research agent's behavior is governed by custom instructions located in deep_research/research_agent/prompts.py. You can modify these to change the workflow, delegation strategies, or researcher behavior.

    Key instruction sets include:

    • RESEARCH_WORKFLOW_INSTRUCTIONS: Defines the 5-step workflow (save request → plan → delegate → synthesize → respond).
    • SUBAGENT_DELEGATION_INSTRUCTIONS: Manages how tasks are split among sub-agents (e.g., 1 sub-agent for simple queries, 1 per element for comparisons).
    • RESEARCHER_INSTRUCTIONS: Guides individual sub-agents on web search limits and the use of the think_tool for reflection.

  3. Setup Deep Research Quickstart

    main

    To set up the Deep Research environment, you must use the uv package manager. Follow these steps:

    1. Install uv:
      curl -LsSf https://astral.sh/uv/install.sh | sh
    2. Navigate to the deep_research directory.
    3. Synchronize the environment:
      uv sync
    4. Configure the required environment variables:
      • ANTHROPIC_API_KEY: Required for Claude models.
      • GOOGLE_API_KEY: Required for Gemini models.
      • TAVILY_API_KEY: Required for web search functionality.
      • LANGSMITH_API_KEY: Recommended for tracing.
    export ANTHROPIC_API_KEY=your_anthropic_api_key_here
export GOOGLE_API_KEY=your_google_api_key_here
export TAVILY_API_KEY=your_tavily_api_key_here
export LANGSMITH_API_KEY=your_langsmith_api_key_here

  4. Run Deep Research via LangGraph Server

    main

    To run the agent with a web interface using the LangGraph Studio, use the langgraph dev command. This will open a local server with a Studio interface for submitting search queries.

    To use a dedicated UI designed for deep agents, you can clone and run the deep-agents-ui repository:

    $ git clone https://github.com/langchain-ai/deep-agents-ui.git
$ cd deep-agents-ui
$ yarn install
$ yarn dev

    After starting the UI, follow the connection instructions in the deep-agents-ui README to link it to your running LangGraph server.

    langgraph dev

  5. Define task-specific sub-agents for context isolation

    main

    Sub-agents in deepagents are used to provide context isolation. You define a sub-agent as a dictionary containing the following keys:

    • name: A unique identifier for the sub-agent.
    • description: A description that helps the orchestrator understand when to delegate tasks to this sub-agent.
    • system_prompt: The specialized instructions for the sub-agent (often formatted with dynamic data like the current date).
    • tools: A list of tools available specifically to this sub-agent.

    Example configuration:

    research_sub_agent = {
    "name": "research-agent",
    "description": "Delegate research to the sub-agent researcher. Only give this researcher one topic at a time.",
    "system_prompt": RESEARCHER_INSTRUCTIONS.format(date=current_date),
    "tools": [tavily_search, think_tool],
}

  6. Configure environment variables for Deep Research Agent

    main

    To run the Deep Research Agent example, you must create a .env file in your project root and populate it with the required API keys. The agent uses Anthropic for reasoning, OpenAI for summarization, Tavily for web search, and LangSmith for LangGraph local server operations.

    Follow these steps:

    1. Copy the .env.example file to a new file named .env.
    2. Replace the placeholder values with your actual API keys.
    # Anthropic API Key (for Claude Sonnet 4)
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# OpenAI API Key (for GPT-4o-mini summarization)
OPENAI_API_KEY=your_openai_api_key_here

# Tavily API Key (for web search)
TAVILY_API_KEY=your_tavily_api_key_here

# LangSmith API Key (required for LangGraph local server)
LANGSMITH_API_KEY=lsv2_pt_your_api_key_here

  7. Create a research agent with deepagents

    main

    To build a specialized research agent using the deepagents package, you should compose four key components: native tools, task-specific tools, task-specific instructions, and task-specific sub-agents. This modular approach allows for better context isolation and specialized capabilities.

    Workflow Summary

    1. Define Tools: Combine native tools with custom tools (e.g., tavily_search for web access and a think_tool for reasoning audits).
    2. Define Instructions: Use prompting techniques like 'Think Like The Agent' (broad-to-narrow search), 'Concrete Heuristics' (setting tool call budgets), and 'Show your thinking' (using a think tool to analyze results).
    3. Define Sub-Agents: Create sub-agents as dictionaries to isolate context. A sub-agent requires a name, description, system_prompt, and a list of tools.
    4. Initialize Agent: Use create_deep_agent to bind the model, tools, instructions, and sub-agents together.
    from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model

# 1. Setup Model
model = init_chat_model(model="anthropic:claude-sonnet-4-5-20250929", temperature=0.0)

# 2. Define Sub-agent
research_sub_agent = {
    "name": "research-agent",
    "description": "Delegate research to the sub-agent researcher.",
    "system_prompt": "Your specialized instructions here",
    "tools": [tavily_search, think_tool],
}

# 3. Create Agent
agent = create_deep_agent(
      model=model,
      tools=[tavily_search, think_tool],
      system_prompt="Main orchestrator instructions",
      subagents=[research_sub_agent],
  )

# 4. Run Agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "your research query"}]
})

  8. Customize the Model for Deep Research

    main

    The default model is claude-sonnet-4-5-20250929. You can override this by passing any LangChain model object to create_deep_agent.

    Supported models include Claude (via init_chat_model) and Gemini (via ChatGoogleGenerativeAI).

    from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# Using Claude
model = init_chat_model(model="anthropic:claude-sonnet-4-5-20250929", temperature=0.0)

# Using Gemini
from langchain_google_genai import ChatGoogleGenerativeAI
model = ChatGoogleGenerativeAI(model="gemini-3-pro-preview")

agent = create_deep_agent(
    model=model,
)

  9. Reference: Deep Research Custom Tools

    main

    The deep research agent includes specific custom tools designed for the research workflow. These are in addition to standard deepagent tools.

    | Tool Name | Description |
|-----------|-------------|
| `tavily_search` | Web search tool that uses Tavily purely as a URL discovery engine. Performs searches using Tavily API to find relevant URLs, fetches full webpage content via HTTP with proper User-Agent headers (avoiding 403 errors), converts HTML to markdown, and returns the complete content without summarization to preserve all information for the agent's analysis. Works with both Claude and Gemini models. |
| `think_tool` | Strategic reflection mechanism that helps the agent pause and assess progress between searches, analyze findings, identify gaps, and plan next steps. |

  10. Invoke a deep agent and process results

    main

    Agents are executed using the .invoke() method, passing a dictionary containing a messages list. The input message should follow the standard role/content format.

    To access files generated by the agent (such as reports), use the files key in the returned dictionary. You can convert file data to a string using file_data_to_string from deepagents.backends.utils.

    # Invocation
result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "research context engineering approaches used to build AI agents",
        }
    ],
})

# Accessing generated files
from deepagents.backends.utils import file_data_to_string
file_content = file_data_to_string(result['files']['/final_report.md'])
    result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "research context engineering approaches used to build AI agents",
            }
        ],
    }, 
)

  11. Use create_deep_agent to initialize an agent

    main

    The create_deep_agent function is the primary entry point for constructing a deep agent. It accepts the following parameters:

    • model: A chat model instance (e.g., from langchain or langchain_google_genai).
    • tools: A list of tools the agent can call.
    • system_prompt: The primary instructions for the agent.
    • subagents: A list of sub-agent dictionaries for delegated tasks.

    Once created, you can visualize the agent's logic using agent.get_graph().draw_mermaid_png().

    from deepagents import create_deep_agent

agent = create_deep_agent(
      model=model,
      tools=tools, 
      system_prompt=INSTRUCTIONS,
      subagents=[research_sub_agent],
  )

  12. Reference: Deep Research Agent environment variables

    main

    The following environment variables are required for the Deep Research Agent example. Ensure these keys are correctly set in your .env file.

    ANTHROPIC_API_KEY=  # Used for Claude Sonnet 4
OPENAI_API_KEY=      # Used for GPT-4o-mini summarization
TAVILY_API_KEY=      # Used for web search
LANGSMITH_API_KEY=    # Required for LangGraph local server (get at https://smith.langchain.com/settings)