Skip to content

overview.mdx

Latest commit

 

History

History
173 lines (144 loc) · 7.77 KB

overview.mdx

File metadata and controls

173 lines (144 loc) · 7.77 KB
title Deep Agents overview
sidebarTitle Overview
description Build agents that can plan, use subagents, and leverage file systems for complex tasks

Deep agents are the easiest way to start building agents and applications powered by LLMs—with builtin capabilities for task planning, file systems for context management, subagent-spawning, and long-term memory. You can use deep agents for any task, including complex, multi-step tasks.

We think of deepagents as an "agent harness". It is the same core tool calling loop as other agent frameworks, but with built-in tools and capabilities.

:::python deepagents is a standalone library built on top of LangChain's core building blocks for agents. It uses the LangGraph runtime for durable execution, streaming, human-in-the-loop, and other features. :::

:::js deepagents is a standalone library built on top of LangChain's core building blocks for agents and using LangGraph's tooling for running agents in production. :::

The deepagents library contains:

  • Deep Agents SDK: A package for building agents that can handle any task
  • Deep Agents CLI: A terminal coding agent built on the Deep Agents SDK

LangChain is the framework that provides the core building blocks for your agents. To learn more about the differences between LangChain, LangGraph, and Deep Agents, see Frameworks, runtimes, and harnesses.

Create a deep agent

:::python

# pip install -qU deepagents
from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

:::

:::js

import * as z from "zod";
// npm install deepagents langchain @langchain/core
import { createDeepAgent } from "deepagents";
import { tool } from "langchain";

const getWeather = tool(
  ({ city }) => `It's always sunny in ${city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string(),
    }),
  },
);

const agent = createDeepAgent({
  tools: [getWeather],
  system: "You are a helpful assistant",
});

console.log(
  await agent.invoke({
    messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
  })
);

:::

See the Quickstart and Customization guide to get started building your own agents and applications with deep agents.

Use [LangSmith](/langsmith/home) to trace requests, debug agent behavior, and evaluate outputs. Set `LANGSMITH_TRACING=true` and your API key to get started.

When to use the Deep Agents

Use the Deep Agents SDK when you want to build agents that can:

  • Handle complex, multi-step tasks that require planning and decomposition
  • Manage large amounts of context through file system tools
  • Swap filesystem backends to use in-memory state, local disk, durable stores, sandboxes, or your own custom backend
  • Delegate work to specialized subagents for context isolation
  • Persist memory across conversations and threads

:::python For building simpler agents, consider using LangChain's create_agent or building a custom LangGraph workflow. :::

:::js For building simpler agents, consider using LangChain's createAgent or building a custom LangGraph workflow. :::

Use the Deep Agents CLI when you want a coding agent on the command line, built on the Deep Agents SDK:

  • Run interactively or non-interactively — use the CLI as a chat-style coding agent, or pipe tasks with -n for scriptable, headless execution.
  • Customize agents with skills and memory.
  • Teach agents as you use them about your preferences, common patterns, and custom project knowledge.
  • Execute code on your machine or in sandboxes.

Core capabilities

Deep agents include a built-in [`write_todos`](/oss/langchain/middleware/built-in#to-do-list) tool that enables agents to break down complex tasks into discrete steps, track progress, and adapt plans as new information emerges. File system tools ([`ls`](/oss/deepagents/harness#file-system-access), [`read_file`](/oss/deepagents/harness#file-system-access), [`write_file`](/oss/deepagents/harness#file-system-access), [`edit_file`](/oss/deepagents/harness#file-system-access)) allow agents to offload large context to in-memory or filesystem storage, preventing context window overflow and enabling work with variable-length tool results. The virtual filesystem is powered by [pluggable backends](/oss/deepagents/backends) that you can swap to fit your use case. Choose from in-memory state, local disk, LangGraph store for cross-thread persistence, [sandboxes](/oss/deepagents/sandboxes) for isolated code execution (Modal, Daytona, Deno), or combine multiple backends with composite routing. You can also implement your own custom backend. A built-in `task` tool enables agents to spawn specialized subagents for context isolation. This keeps the main agent's context clean while still going deep on specific subtasks. Extend agents with persistent memory across threads using LangGraph's [Memory Store](/oss/langgraph/persistence#memory-store). Agents can save and retrieve information from previous conversations.

Get started

:::python Build your first deep agent Learn about customization options for the SDK Choose and configure pluggable filesystem backends Execute code in isolated environments Use the Deep Agents CLI See the deepagents API reference :::

:::js Build your first deep agent Learn about customization options for the SDK Choose and configure pluggable filesystem backends Use the Deep Agents CLI See the deepagents API reference :::