Quickstart

This guide walks you through creating your first deep agent with the Deep Agents SDK. Use the SDK for maximum flexibility and host agents yourself or run a custom LangSmith Deployment. To run agents in production without having to manage infrastructure, see the Managed Deep Agents quickstart instead. You will build a research agent that can conduct research and write reports.

Build the Deep Agents research quickstart

Using an AI coding assistant?

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

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

npm install deepagents langchain @langchain/core

yarn add deepagents langchain @langchain/core

pnpm add deepagents langchain @langchain/core

Google, OpenAI, and Anthropic all provide built-in web search tools: no extra package or API key required. If you use a different provider or prefer Tavily for search, install the Tavily package as well:

npm install @langchain/tavily

Step 2: Set up your API keys

export GOOGLE_API_KEY="your-api-key"

export OPENAI_API_KEY="your-api-key"

export ANTHROPIC_API_KEY="your-api-key"

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

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

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

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

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

If you are using the LangSmith LLM Gateway, traffic to providers is routed through LangSmith. Use the gateway key as the API key instead.

Step 3: Create a search tool

Google, OpenAI, and Anthropic offer built-in web search tools that run server-side: no extra package or API key needed. Pass a provider tool dict directly to create_deep_agent.

Provider search (recommended)
Tavily (any provider)

import { createDeepAgent } from "deepagents";

// Google's built-in search — no extra install or API key needed
const internetSearch = { googleSearch: {} };

import { createDeepAgent } from "deepagents";

// OpenAI's built-in web search — no extra install or API key needed
const internetSearch = { type: "web_search_preview" };

import { createDeepAgent } from "deepagents";

// Anthropic's built-in web search — no extra install or API key needed
const internetSearch = { type: "web_search_20250305", name: "web_search" };

import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";
import { z } from "zod";

const internetSearch = tool(
  async ({
    query,
    maxResults = 5,
    topic = "general",
    includeRawContent = false,
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
    includeRawContent?: boolean;
  }) => {
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,
      includeRawContent,
      topic,
    });
    return await tavilySearch._call({ query });
  },
  {
    name: "internet_search",
    description: "Run a web search",
    schema: z.object({
      query: z.string().describe("The search query"),
      maxResults: z
        .number()
        .optional()
        .default(5)
        .describe("Maximum number of results to return"),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .default("general")
        .describe("Search topic category"),
      includeRawContent: z
        .boolean()
        .optional()
        .default(false)
        .describe("Whether to include raw content"),
    }),
  },
);

Step 4: Create a deep agent

Pass your search tool and model to create_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.

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `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.
`;

const agent = createDeepAgent({
  model: "google:gemini-3.6-flash",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `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.
`;

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `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.
`;

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `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.
`;

const agent = createDeepAgent({
  model: "openrouter:z-ai/glm-5.2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `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.
`;

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `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.
`;

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `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.
`;

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

Step 5: Set up LangSmith tracing

In an agent-based workspace, create an agent once before sending traces. Use agent addressing to select its identifier and environment. If an integration requires project_name, use the selected environment’s tracer_session_name as a compatibility value.

LangSmith provides you with visibility into your agent’s execution, allowing you to view tool calls, subagent delegation, and LLM responses. Sign up at smith.langchain.com, create an API key, and set these environment variables:

export LANGSMITH_AGENT_ID="<your-agent-id>"
export LANGSMITH_AGENT_ENVIRONMENT="local"
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

Step 6: Run the agent

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

// Print the agent's response
console.log(result.messages[result.messages.length - 1].content);

How does it work?

Your deep agent automatically:

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.

To add structured task planning with write_todos, opt in with TodoListMiddleware. See Task planning.

Examples

For examples of agents and patterns 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 your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Deployment

Execution environment

Context management

Delegation

Steering

Middleware

Frontend

Protocols

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: Set up LangSmith tracing

Step 6: Run the agent

How does it work?

Examples

Streaming

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: Set up LangSmith tracing

​Step 6: Run the agent

​How does it work?

​Examples

​Streaming

​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: Set up LangSmith tracing

Step 6: Run the agent

How does it work?

Examples

Streaming

Next steps