deepagents

Description

The batteries-included agent harness.

Deep Agents is an agent harness. An opinionated, ready-to-run agent out of the box. Instead of wiring prompts, tools, and context management yourself, you get a working agent immediately and customize what you need.

What's included:

Planning — write_todos for task breakdown and progress tracking
Filesystem — read_file, write_file, edit_file, ls, glob, grep for working memory
Sub-agents — task for delegating work with isolated context windows
Smart defaults — built-in prompt and middleware that make these tools useful out of the box
Context management — file-based workflows to keep long tasks manageable

[!NOTE] Looking for the Python package? See langchain-ai/deepagents.

Quickstart

npm install deepagents
# or
pnpm add deepagents
# or
yarn add deepagents

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent();

const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content: "Research LangGraph and write a summary in summary.md",
    },
  ],
});

The agent can plan, read/write files, and manage longer tasks with sub-agents and filesystem tools.

[!TIP] For developing, debugging, and deploying AI agents and LLM applications, see LangSmith.

Customization

Add tools, swap models, and customize prompts as needed:

import { ChatOpenAI } from "@langchain/openai";
import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: new ChatOpenAI({ model: "gpt-5", temperature: 0 }),
  tools: [myCustomTool],
  systemPrompt: "You are a research assistant.",
});

See the JavaScript Deep Agents docs for full configuration options.

LangGraph Native

createDeepAgent returns a compiled LangGraph graph, so you can use streaming, Studio, checkpointers, and other LangGraph features.

Why Use It

100% open source — MIT licensed and extensible
Provider agnostic — works with tool-calling chat models
Built on LangGraph — production runtime with streaming and persistence
Batteries included — planning, file access, sub-agents, and defaults out of the box
Fast to start — install and run with sensible defaults
Easy to customize — add tools/models/prompts when you need to

Documentation

docs.langchain.com - Concepts and guides
Examples - Working agents and patterns
LangChain Forum - Community discussion and support

Security

Deep Agents follows a "trust the LLM" model. The agent can do anything its tools allow. Enforce boundaries at the tool/sandbox level, not by expecting the model to self-police. See the security policy for more information.

Classes

Class

BaseSandbox

Base sandbox implementation with execute() as the only abstract method.

Class

CompositeBackend

Backend that routes file operations to different backends based on path prefix.

Class

ContextHubBackend

Backend that stores files in a LangSmith Hub agent repo (persistent).

Class

FilesystemBackend

Backend that reads and writes files directly from the filesystem.

Class

LangSmithSandbox

LangSmith Sandbox backend for deepagents.

Class

LocalShellBackend

Filesystem backend with unrestricted local shell command execution.

Class

SandboxError

Custom error class for sandbox operations.

Class

StateBackend

Backend that stores files in agent state (ephemeral).

Class

StoreBackend

Backend that stores files in LangGraph's BaseStore (persistent).

Class

ConfigurationError

Thrown when createDeepAgent receives invalid configuration.

Class

BaseSandbox

Base sandbox implementation with execute() as the only abstract method.

Class

CompositeBackend

Backend that routes file operations to different backends based on path prefix.

Class

ContextHubBackend

Backend that stores files in a LangSmith Hub agent repo (persistent).

Class

FilesystemBackend

Backend that reads and writes files directly from the filesystem.

Class

LangSmithSandbox

LangSmith Sandbox backend for deepagents.

Class

LocalShellBackend

Filesystem backend with unrestricted local shell command execution.

Class

SandboxError

Custom error class for sandbox operations.

Class

StateBackend

Backend that stores files in agent state (ephemeral).

Class

StoreBackend

Backend that stores files in LangGraph's BaseStore (persistent).

Class

ConfigurationError

Thrown when createDeepAgent receives invalid configuration.

Functions

Function

createDeepAgent

Create a Deep Agent.

Function

adaptBackendProtocol

Adapt a v1 BackendProtocol to BackendProtocolV2.

Function

adaptSandboxProtocol

Adapt a sandbox backend from v1 to v2 interface.

Function

buildGrepResultsDict

Group structured matches into the legacy dict form used by formatters.

Function

checkEmptyContent

Check if content is empty and return warning message.

Function

createFileData

Create a FileData object.

Function

fileDataToString

Convert FileData to plain string content.

Function

formatContentWithLineNumbers

Format file content with line numbers (cat -n style).

Function

formatGrepMatches

Format structured grep matches using existing formatting logic.

Function

formatGrepResults

Format grep search results based on output mode.

Function

formatReadResponse

Format file data for read response with line numbers.

Function

getMimeType

Determine MIME type from a file path's extension.

Function

globSearchFiles

Search files dict for paths matching glob pattern.

Function

grepMatchesFromFiles

Return structured grep matches from an in-memory files mapping.

Function

grepSearchFiles

Search file contents for literal text pattern.

Function

isFileDataBinary

Type guard to check if FileData contains binary content (Uint8Array).

Function

isFileDataV1

Type guard to check if FileData is v1 format (content as line array).

Function

isTextMimeType

Check whether a MIME type represents text content.

Function

migrateToFileDataV2

Convert FileData to v2 format, joining v1 line arrays into a single string.

Function

performStringReplacement

Perform string replacement with occurrence validation.

Function

sanitizeToolCallId

Sanitize tool_call_id to prevent path traversal and separator issues.

Function

truncateIfTooLong

Truncate list or string result if it exceeds token limit (rough estimate: 4 chars/token).

Function

updateFileData

Update FileData with new content, preserving creation timestamp.

Function

validateFilePath

Validate and normalize a file path for security.

Function

validatePath

Validate and normalize a directory path.

Function

isSandboxBackend

Type guard to check if a backend supports execution.

Function

isSandboxProtocol

Type guard to check if a backend is a sandbox protocol (v1 or v2).

Function

createSettings

Create a Settings instance with detected environment.

Function

findProjectRoot

Find the project root by looking for .git directory.

Function

computeSummarizationDefaults

Compute summarization defaults based on model profile.

Function

createAsyncSubAgentMiddleware

Function

createCompletionCallbackMiddleware

Create a completion callback middleware for async subagents.

Function

createFilesystemMiddleware

Create filesystem middleware with all tools and features.

Function

createHarnessProfile

Create a frozen HarnessProfile from user-provided options.

Function

createMemoryMiddleware

Create middleware for loading agent memory from AGENTS.md files.

Function

createPatchToolCallsMiddleware

Create middleware that enforces strict tool call / tool response parity in

Function

createSkillsMiddleware

Create backend-agnostic middleware for loading and exposing agent skills.

Function

createSubAgentMiddleware

Create subagent middleware with task tool

Function

createSummarizationMiddleware

Create summarization middleware with backend support for conversation history offloading.

Function

getHarnessProfile

Look up the HarnessProfile for a model spec string.

Function

isAsyncSubAgent

Type guard to distinguish async SubAgents from sync SubAgents/CompiledSubAgents.

Function

isSandboxBackend

Type guard to check if a backend supports execution.

Function

isSandboxProtocol

Type guard to check if a backend is a sandbox protocol (v1 or v2).

Function

listSkills

List skills from user and/or project directories.

Function

parseHarnessProfileConfig

Parse an untrusted JSON/YAML object into a validated

Function

parseSkillMetadata

Parse YAML frontmatter from a SKILL.md file per Agent Skills spec.

Function

registerHarnessProfile

Function

serializeProfile

Serialize a HarnessProfile to a JSON-compatible object.

Function

adaptBackendProtocol

Adapt a v1 BackendProtocol to BackendProtocolV2.

Function

adaptSandboxProtocol

Adapt a sandbox backend from v1 to v2 interface.

Function

createDeepAgent

Create a Deep Agent.

Function

createSettings

Create a Settings instance with detected environment.

Function

createSubagentTransformer

Native transformer that correlates task tool calls into

Function

findProjectRoot

Find the project root by looking for .git directory.

Function

appendToSystemMessage

Append text to a system message.

Function

createContentPreview

Create a preview of content showing head and tail with truncation marker.

Function

patchDanglingToolCalls

Patch tool call / tool response parity in a messages array.

Function

prependToSystemMessage

Prepend text to a system message.

Function

computeSummarizationDefaults

Compute summarization defaults based on model profile.

Function

createAsyncSubAgentMiddleware

Function

createCompletionCallbackMiddleware

Create a completion callback middleware for async subagents.

Function

createFilesystemMiddleware

Create filesystem middleware with all tools and features.

Function

createMemoryMiddleware

Create middleware for loading agent memory from AGENTS.md files.

Function

createPatchToolCallsMiddleware

Create middleware that enforces strict tool call / tool response parity in

Function

createSkillsMiddleware

Create backend-agnostic middleware for loading and exposing agent skills.

Function

createSubAgentMiddleware

Create subagent middleware with task tool

Function

createSummarizationMiddleware

Create summarization middleware with backend support for conversation history offloading.

Function

isAsyncSubAgent

Type guard to distinguish async SubAgents from sync SubAgents/CompiledSubAgents.

Function

decidePathAccess

Evaluate permission rules against an operation + path and return the

Function

globMatch

Test whether path matches a glob pattern.

Function

validatePath

Canonicalize and validate an absolute path before permission checking.

Function

validatePermissionPaths

Validate permission rule paths at setup time. Throws if any path is

Function

applyProfilePrompt

Apply a profile's prompt overlay to a base prompt string.

Function

mergeProfiles

Merge two harness profiles, layering override on top of base.

Function

validateProfileKey

Normalize and validate a profile registry key.

Function

createHarnessProfile

Create a frozen HarnessProfile from user-provided options.

Function

getHarnessProfile

Look up the HarnessProfile for a model spec string.

Function

parseHarnessProfileConfig

Parse an untrusted JSON/YAML object into a validated

Function

registerHarnessProfile

Function

serializeProfile

Serialize a HarnessProfile to a JSON-compatible object.

Function

isHarnessProfile

Type guard: is this a fully-constructed HarnessProfile (frozen with

Function

applyProfilePrompt

Apply a profile's prompt overlay to a base prompt string.

Function

createHarnessProfile

Create a frozen HarnessProfile from user-provided options.

Function

getHarnessProfile

Look up the HarnessProfile for a model spec string.

Function

mergeProfiles

Merge two harness profiles, layering override on top of base.

Function

parseHarnessProfileConfig

Parse an untrusted JSON/YAML object into a validated

Function

registerHarnessProfile

Function

serializeProfile

Serialize a HarnessProfile to a JSON-compatible object.

Function

listSkills

List skills from user and/or project directories.

Function

parseSkillMetadata

Parse YAML frontmatter from a SKILL.md file per Agent Skills spec.

Function

createSubagentTransformer

Native transformer that correlates task tool calls into

Function

isAnthropicModel

Detect whether a model is an Anthropic model.

Function

createAgentMemoryMiddleware

deprecated

Create middleware for loading agent-specific long-term memory.