Primary graph assembly module for Deep Agents.
Provides create_deep_agent, the main entry
point for constructing a fully configured deep agent with planning, filesystem,
subagent, and summarization middleware.
Base spec for general-purpose subagent (caller adds model, tools, middleware).
Default base system prompt for every deep agent (BASE).
The final system prompt sent to the model is composed from up to four named parts:
USER — the system_prompt= argument to create_deep_agent (str or
SystemMessage); when unset, no USER segment is included.BASE — this constant.CUSTOM — HarnessProfile.base_system_prompt. When set on a matching
profile, replaces BASE outright; when unset, BASE is used.SUFFIX — HarnessProfile.system_prompt_suffix. When set on a
matching profile, appended last; when unset, no SUFFIX segment is
included.The order is always USER -> (BASE or CUSTOM) -> SUFFIX, joined by
blank lines (\n\n). Two invariants follow:
USER is always at the front, so caller instructions take precedence
over SDK and profile content regardless of which model is selected.SUFFIX is always at the end, so model-tuning guidance sits closest
to the conversation history (where the model attends most).When USER is a SystemMessage, the right-hand assembly is appended as
an additional text content block onto the message's existing
content_blocks list, preserving any cache_control markers the caller
set.
See create_deep_agent's system_prompt parameter or
Prompt assembly
for the full assembly order.
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. That value targets a
decorator-wrapped frame layout; when called directly from a deprecated
method's body the warning is attributed one frame too high (above the
user's call site). This wrapper captures the formatted upstream warning
and re-emits it with an explicit stacklevel, so the warning points at
the user's call site.
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 initialization behavior registered in the
ProviderProfile registry. Built-in registrations supply the OpenAI
Responses API default and OpenRouter app attribution headers; users can
layer additional providers or overrides via register_provider_profile.
Return fields annotated with PrivateStateAttr across state schemas.
Create a Deep Agents SummarizationMiddleware with model-aware defaults.
deepagentsThe Deep Agents SummarizationMiddleware wraps
langchain.agents.middleware.SummarizationMiddleware to add behavior
long-running, file-aware agents need. Prefer LangChain's middleware
directly if none of the below apply:
/conversation_history/{thread_id}.md (default path) on the
configured backend before the summary replaces them, and the
summary embeds that path so the agent can re-open it via
read_file when FilesystemMiddleware is registered. LangChain
drops evicted messages with no recovery path.write_file /
edit_file arguments in older messages are clipped at a lower
threshold than full compaction, often reclaiming enough context
to skip summarizing. Configured via truncate_args_settings.ContextOverflowError fallback. On a provider over-budget
rejection the middleware summarizes and retries instead of
bubbling the error up._summarization_event field via wrap_model_call,
leaving state["messages"] intact. LangChain rewrites it with
RemoveMessage(id=REMOVE_ALL_MESSAGES) from before_model.
Preserving the raw log enables replay, evals, and shared state
with SummarizationToolMiddleware's compact_conversation tool.trigger=None and
keep=("messages", 20). This factory picks fraction-based
defaults from the model's profile when max_input_tokens is
exposed, falling back to fixed counts otherwise — see
compute_summarization_defaults.Create a deep agent.
By default, this agent has access to the following tools:
write_todos: manage a todo listls, read_file, write_file, edit_file, glob, grep: file operationsexecute: run shell commandstask: call subagentsThe execute tool allows running shell commands if the backend implements
SandboxBackendProtocol.
For non-sandbox backends, the execute tool will return an error message.
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="claude-sonnet-4-6")).
Used as a fallback when model=None is passed to create_deep_agent.
Requires ANTHROPIC_API_KEY to be set in the environment.
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 checkpointed after each agent step.
Reads and writes go through LangGraph's CONFIG_KEY_READ /
CONFIG_KEY_SEND so that state updates are queued as proper channel
writes rather than returned as files_update dicts.
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.
All file data is represented as dicts with the following structure:
{
"content": str, # Text content (utf-8) or base64-encoded binary
"encoding": str, # "utf-8" for text, "base64" for binary data
"created_at": str, # ISO format timestamp
"modified_at": str, # ISO format timestamp
}Specification for an async subagent running on a remote Agent Protocol server.
Async subagents connect to any Agent Protocol-compliant server via the LangGraph SDK. They run as background tasks that the main agent can monitor and update.
Compatible with LangGraph Platform (managed) and self-hosted servers.
Authentication for LangGraph Platform is handled automatically by the SDK
via environment variables (LANGGRAPH_API_KEY, LANGSMITH_API_KEY, or
LANGCHAIN_API_KEY). For self-hosted servers, pass custom auth via
headers.
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 the synchronous
SubAgentMiddleware, async subagents return immediately with a task ID,
allowing the main agent to continue working while subagents execute.
Works with any Agent Protocol-compliant server — LangGraph Platform (managed) or self-hosted (e.g. a FastAPI server implementing the Agent Protocol spec).
Task IDs are persisted in the agent state under async_tasks so they
survive context compaction/offloading and can be accessed programmatically.
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.
Files can be stored using any backend that implements the
BackendProtocol.
If the backend implements
SandboxBackendProtocol,
an execute tool is also added for running shell commands.
This middleware also automatically evicts large tool results to the file system when they exceed a token threshold, preventing context window saturation.
A single access rule for filesystem operations.
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 constructor for the full argument list.
Middleware to patch dangling tool calls in the messages history.
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 content on demand).
Skills are loaded in source order with later sources overriding earlier ones.
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.
CompiledSubAgent runnables are used as provided. They do not
inherit create_deep_agent(state_schema=...); if the runnable
needs custom state fields, compile it with a compatible state
schema yourself.
When the subagent completes, the parent reads the returned state:
if structured_response is non-None, it is JSON-serialized and used as
the ToolMessage content; otherwise, the last non-empty AIMessage
text is used.
Specification for an agent.
When using create_deep_agent, subagents automatically receive
a default middleware stack before any custom middleware specified in
this spec.
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 tasks that require multiple steps, or tasks that require a lot of context to resolve.
A chief benefit of subagents is that they can handle multi-step tasks, and then return a clean, concise response to the main agent.
Subagents are also great for different domains of expertise that require a narrower subset of tools and focus.
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 documentation
for more details.
These settings only affect the default subagent that create_deep_agent
inserts when the caller does not explicitly provide a subagent named
general-purpose.
AgentState with DeltaChannel on messages to reduce checkpoint growth from O(N²) to O(N).