Looking for the JS/TS version? Check out Deep Agents.js.
To help you ship LangChain apps to production faster, check out LangSmith. LangSmith is a unified developer platform for building, testing, and monitoring LLM applications.
uv add deepagentsDeep Agents is an open source agent harness — an opinionated agent that runs out of the box. Extend, override, or replace any piece.
Principles:
Features include:
from deepagents import create_deep_agent
agent = create_deep_agent(
model="openai:gpt-6-astra",
tools=[my_custom_tool],
system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})The agent can plan, read/write files, and manage its own context. Add your own tools, swap models, customize prompts, configure sub-agents, and more. For a full overview and quickstart of Deep Agents, the best resource is our docs.
Acknowledgements: This project was primarily inspired by Claude Code, and initially was largely an attempt to see what made Claude Code general purpose, and make it even more so.
LangGraph is the graph runtime. LangChain's create_agent is a minimal agent harness on top of it. Deep Agents is a more opinionated harness on top of create_agent — same building blocks, but with filesystem, sub-agents, context management, and skills bundled in. For how the three relate, see the LangChain ecosystem overview.
Yes. Any model that supports tool calling works — frontier APIs (OpenAI, Anthropic, Google), open-weight models hosted on providers like Baseten or Fireworks, and self-hosted models via Ollama, vLLM, or llama.cpp. Use any LangChain chat model.
Yes! Deep Agents is built on LangGraph, designed for production agent deployments. Pair it with LangSmith for tracing, evaluation, and monitoring. See Going to production for the full guide.
All three are layers in the same stack — see the LangChain ecosystem overview for how they relate. Use Deep Agents when you want the full harness — planning, context management, delegation — out of the box. Use LangChain's create_agent when you want a lighter harness without the bundled middleware. Drop to LangGraph when the agent loop itself isn't the right shape and you need a custom graph.
The layers compose: any LangGraph CompiledStateGraph can be passed in as a sub-agent to a Deep Agent, so custom orchestration plugs in alongside the harness's defaults.
See our Releases and Versioning policies.
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.
As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
For detailed information on how to contribute, see the Contributing Guide.
AgentState with DeltaChannel on messages to reduce checkpoint growth from O(N²) to O(N).
Declarative configuration for constructing a chat model.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the [versioning document
Edits applied to the auto-added general-purpose subagent.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the [versioning docum
Declarative harness-profile config for YAML/JSON-backed profiles.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the [versioning
Runtime configuration for deep agent behavior.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the [versioning documentation](htt
Repair small Nemotron filesystem tool-call and tool-result quirks.
Append a continuation notice to exactly-at-limit read_file results.
Retry transient provider 429s around model calls.
Mirror standard LangChain tool-call fields into ChatNVIDIA payload metadata.
Remove preserved <think> blocks from normal assistant content.
Repair tool calls emitted as text content instead of structured calls.
Stop Ultra3-specific tool loops before they consume runaway context.
State schema for one-shot Nemotron policy nudges.
Inject lightweight policy nudges for common Ultra3 agent-control misses.
State schema for FollowupDisciplineMiddleware.
Send Ultra3 back once when it asks redundant follow-up questions.
State schema for EntityResolutionGuardMiddleware.
Send Ultra3 back once when it finalizes with unresolved or mis-bound IDs.
State schema for FinalAnswerGuardMiddleware.
Send Ultra3 back once when a final answer drops obvious required details.
Specification for a declarative subagent.
By default the subagent is isolated: it receives only the delegated task
description. Setting mode="fork" makes it continue the parent's
conversation inste
A pre-compiled agent spec.
The runnable's state schema must include a 'messages' key.
This is required for the subagent to communicate results back to the main agent.
Input schema for the task tool.
Middleware for providing subagents to an agent via a task tool.
This middleware adds a task tool to the agent that can be used
to invoke subagents.
Subagents are useful for handling complex task
Replace multimodal input blocks the active model can't accept with a text notice.
Without it, a request carrying content the model can't accept (e.g. an image sent to a text-only model) fails, and si
A single access rule for filesystem operations.
State for the filesystem middleware.
Input schema for the ls tool.
Input schema for the read_file tool.
Input schema for read_file when the optional video frame extraction is available.
Identical to ReadFileSchema; only the offset/limit descriptions differ
to document their video semantics (int
Input schema for the write_file tool.
Input schema for the edit_file tool.
Input schema for the delete tool.
Input schema for the glob tool.
Input schema for the grep tool.
Input schema for the execute tool.
Middleware for providing filesystem and optional execution tools to an agent.
This middleware adds filesystem tools to the agent: ls, read_file, write_file,
edit_file, glob, and grep.
Fi
Specification for an async subagent running on a remote Agent Protocol server.
Async subagents connect to any Agent Protocol-compliant server via the
A tracked async subagent task persisted in agent state.
State extension for async subagent task tracking.
Input schema for the start_async_task tool.
Input schema for the check_async_task tool.
Input schema for the update_async_task tool.
Input schema for the cancel_async_task tool.
Input schema for the list_async_tasks tool.
Middleware for async subagents running on remote Agent Protocol servers.
This middleware adds tools for launching, monitoring, and updating background tasks on remote Agent Protocol servers. Unlike t
Metadata for a skill per Agent Skills specification (https://agentskills.io/specification).
State for the skills middleware.
State update for the skills middleware.
Middleware for loading and exposing agent skills to the system prompt.
Loads skills from backend sources and injects them into the system prompt using progressive disclosure (metadata first, full con
Input schema for the compact_conversation tool.
Represents a summarization event.
Dictionary-based summarization trigger with AND semantics.
Settings for truncating large tool-call arguments in older messages.
This is a lightweight, pre-summarization optimization that fires at a lower token threshold than full conversation compaction. Whe
State for the summarization middleware.
Extends AgentState with a private field for tracking summarization events.
Default settings computed from model profile.
Middleware that provides a compact_conversation tool for manual compaction.
This middleware composes with a SummarizationMiddleware instance, reusing
its summarization engine (model, backend, tri
State schema for MemoryMiddleware.
State update for MemoryMiddleware.
Middleware for loading agent memory from AGENTS.md files.
Loads memory content from configured sources and injects into the system prompt. Supports multiple sources that are combined together. See
A rendered preview plus a record of what was left out to build it.
The flags are reported by the code that built text, never inferred from
the rendered bytes — a literal `... [N lines truncated] ..
Per-criterion grader verdict when the criterion passes.
Per-criterion grader verdict when the criterion fails.
One grader evaluation, appended to _rubric_evaluations each iteration.
Consumers can read any field without guarding against absence since all
fields are always populated by _build_evaluation and
State schema for RubricMiddleware.
Only rubric is part of the public I/O schema -- callers write a
rubric and read the improved agent response back from messages.
Everything else is bookkeepin
Structured output the grader sub-agent must emit.
Passed as response_format=GraderResponse to create_agent so the
underlying provider's structured output strategy is auto-selected.
Middleware that drives self-evaluated iteration against a rubric.
The middleware activates only when a caller passes a rubric on
invocation state. With no rubric, both before_agent and `after_age
Middleware to patch dangling tool calls in the messages history.
Raised when PyAV cannot produce frames for the requested window.
LangSmith sandbox implementation conforming to SandboxBackendProtocol.
Filesystem backend with unrestricted local shell command execution.
This backend extends FilesystemBackend to add shell command execution
capabilities. Commands are executed directly on the host sy
A glob pattern the shared matcher refuses to compile.
Subclasses ValueError so existing except ValueError handlers keep
working. Callers that catch this specific type can label the failure a
*pat
Backend that reads and writes files directly from the filesystem.
Files are accessed using their actual filesystem paths. Relative paths are resolved relative to the current working directory. Conten
Backend that stores files in a LangSmith Hub agent repo (persistent).
Backend that stores files in agent state (ephemeral).
Uses LangGraph's state management and checkpointing. Files persist within a conversation thread but not across threads. State is automatically ch
Result of a single file download operation.
The response is designed to allow partial success in batch operations.
The errors are standardized using FileOperationError literals for certain
recover
Result of a single file upload operation.
The response is designed to allow partial success in batch operations.
The errors are standardized using FileOperationError literals for certain
recoverab
Structured file listing info.
Minimal contract used across backends. Only path is required.
Other fields are best-effort and may be absent depending on backend.
A non-matching line surrounding a grep match, used for context_lines.
A single match from a grep search.
Data structure for storing file contents with metadata.
Result from backend read operations.
Result from backend write operations.
Result from backend edit operations.
Result from backend delete operations.
Result from backend ls operations.
Result from backend grep operations.
Result from backend glob operations.
Protocol for pluggable memory backends (single, unified).
Backends can store files in different locations (state, filesystem, database, etc.) and provide a uniform interface for file operations.
Fil
Result of code execution.
Simplified schema optimized for LLM consumption.
Machine-readable metadata attached to an execute tool result.
Carried on ToolMessage.artifact alongside the model-facing content, so
callers can react to shell failures. artifact is None in
Result of BaseSandbox.execute_with_offload.
offloaded describes the capture mechanism and is kept off ExecuteResponse
(which an o
Extension of BackendProtocol that adds shell command execution.
Designed for backends running in isolated environments (containers, VMs, remote hosts).
Adds execute()/aexecute() for shell comm
Base sandbox implementation with execute() as the core abstract method.
This class provides default implementations for all protocol methods. File listing, grep, and glob use shell commands via `ex
Routes file operations to different backends by path prefix.
Matches paths against route prefixes (longest first) and delegates to the corresponding backend. Unmatched paths use the default backend.
Backend that stores files in LangGraph's BaseStore (persistent).
Uses LangGraph's Store for persistent, cross-conversation storage. Files are organized via namespaces and persist across all threads.
Resolve a model string to a BaseChatModel.
If model is already a BaseChatModel, returns it unchanged.
String models are resolved via init_chat_model, composed with any
provider-specific init
Extract the provider-native model identifier from a chat model.
Providers do not agree on a single field name for the identifier. Some use
model_name, while others use model.
Extract the provider name from a chat model instance.
Uses the model's _get_ls_params method. The base BaseChatModel
implementation derives ls_provider from the class name, and all major
provid
Check whether a model targets AWS Bedrock.
Check whether a model instance already matches a string model spec.
Bare specs match by model identifier. Provider-prefixed specs match by both model identifier and provider when the current model ex
Create a deep agent.
By default, this agent has access to the following tools:
ls, read_file, write_file, edit_file, glob, grep: file operationsexecute: run shell commandsValidate a provider or provider:model profile registry key.
The first colon separates the provider from the complete model identifier. Providers must not contain colons, while model identifiers m
Raise if the installed langchain-openrouter is below the minimum.
If the package is not installed at all the check is skipped;
init_chat_model will surface its own missing-dependency error downst
Register the built-in OpenRouter provider profile.
Register the built-in NVIDIA provider profile.
Register a ProviderProfile for a provider or specific model.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the [versioning do
Look up the ProviderProfile for a model spec.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the [versioning documentation](ht
Compose init_chat_model kwargs from the registered profile for spec.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the [ver
Register the built-in OpenAI provider profile.
Register the built-in Claude Sonnet 4.6 harness profile.
Register a harness profile for a provider or specific model.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the [versioning docu
Register the built-in Nemotron 3 Ultra harness profile.
Register the built-in Codex harness profile for each Codex spec.
Register the built-in Claude Haiku 4.5 harness profile.
Register the built-in Claude Opus 4.7 harness profile.
Append provider-specific prompt caching middleware.
Create a runnable agent from a raw SubAgent spec.
This is the shared entrypoint for the create_agent path used by
raw subagent specs. Pre-compiled CompiledSubAgent runnables are already
created
Return fields annotated with PrivateStateAttr across state schemas.
Annotations are resolved at runtime, so a schema whose PrivateStateAttr
annotation references a TYPE_CHECKING-only name canno
Check if a backend supports command execution.
For CompositeBackend,
checks if the default backend supports execution.
For other backends, checks i
Compute default summarization settings based on model profile.
Create a Deep Agents SummarizationMiddleware with model-aware defaults.
Why this exists in deepagents
The Deep Agents SummarizationMiddleware wraps
`langchain.agents.middleware.Summarizatio
Create a SummarizationToolMiddleware with model-aware defaults.
Convenience factory: builds a SummarizationMiddleware via
[create_summarization_middleware][deepagents.middleware.summarization.c
Append text to a system message.
Return whether the optional video dependencies appear to be installed.
Uses importlib.util.find_spec, which checks that av and Pillow are
discoverable rather than performing a full import. A di
Decode sampled frames from a video byte payload.
Emit a deprecation warning with caller-controlled stack attribution.
langchain_core.warn_deprecated formats a standard message but hardcodes
stacklevel=4 in its internal warnings.warn call. Tha
Reset the @deprecated decorator's dedupe flag for testing.
The langchain_core @deprecated decorator emits each warning at most once
per process via a closure-bound warned flag. Tests that asser
Compile a grep include-glob into a matcher with ripgrep-like semantics.
Provides one shared include-glob behavior for every backend so the same
grep(..., glob=...) call closely mirrors ripgrep for
Return a bounded, path-safe component for a tool call ID.
Format file content with line numbers.
Chunks lines longer than MAX_LINE_LENGTH with continuation markers
(e.g., 5.1, 5.2). Line markers are separated from source content
with two spaces so sou
Check if content is empty and return warning message.
Convert current or legacy persisted file content to a string.
Create a FileData object with timestamps.
Update FileData with new content, preserving creation timestamp.
Floor a requested read window at a zero offset and zero lines.
Models occasionally emit degenerate read_file arguments (offset=-1,
limit=0). Clamping offset keeps backends from reporting a li
Slice file data to the requested line range without formatting.
The returned ReadResult carries the raw (unformatted) window in
file_data; line-number formatting is applied downstream by the
midd
Perform string replacement with occurrence validation.
Truncate list or string result if it exceeds token limit (rough estimate: 4 chars/token).
Normalize backslash separators to forward slashes for PurePosixPath use.
Backends running on Windows return OS-native paths using backslashes.
PurePosixPath treats backslashes as literal filename
Validate and normalize file path for security.
Ensures paths are safe to use by preventing directory traversal attacks and enforcing consistent formatting. All paths are normalized to use forward sla
Return structured grep matches from an in-memory files mapping.
Performs literal text search (not regex).
Returns a GrepResult with matches on success. When max_count is set, at
most that many m
Group structured matches into the legacy dict form used by formatters.
Format structured grep matches using existing formatting logic.
Return a hint when a pattern looks like an (unsupported) regex.
grep matches literal text, so regex metacharacters are searched verbatim
and silently miss. Callers gate this on a no-match result; t
Check whether a backend class's execute accepts a timeout kwarg.
Older backend packages didn't lower-bound their SDK dependency, so they
may not accept the timeout keyword added to
[`SandboxBac
Get the default model for Deep Agents.
Deprecated since 0.5.3; will be removed in deepagents==1.0.0.
Construct your model explicitly (e.g.,
`ChatAnthropic(model_name="