deepagents

Names of the built-in filesystem tools that can be passed to FilesystemMiddleware(tools=...).

Create a deep agent.

By default, this agent has access to the following tools:

• ls, read_file, write_file, edit_file, glob, grep: file operations
• execute: run shell commands
• task: call subagents

The execute tool allows running shell commands if the backend implements SandboxBackendProtocol. For non-sandbox backends, the execute tool will return an error message.

AgentState with DeltaChannel on messages to reduce checkpoint growth from O(N²) to O(N).

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 / LangSmith Deployment (managed) and self-hosted servers.

Authentication for LangGraph Platform / LangSmith Deployment 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. Its results carry ExecuteArtifact metadata on ToolMessage.artifact.

This middleware also automatically evicts large tool results to the file system when they exceed a token threshold, preventing context window saturation.

When using create_agent directly, add UnsupportedContentMiddleware last in the middleware list, so read_file results the model can't accept are replaced with a text notice. create_deep_agent adds it automatically.

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 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_agent return without modifying state, so the middleware is safe to include unconditionally in a create_deep_agent stack.

A pre-compiled agent spec.

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

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.

These settings only affect the default subagent that create_deep_agent inserts when the caller does not explicitly provide a subagent named general-purpose.

Runtime configuration for deep agent behavior.

A HarnessProfile describes prompt-assembly, tool visibility, middleware, and default-subagent adjustments applied by create_deep_agent once a chat model has been constructed. Profiles are registered via register_harness_profile under a provider key ("openai") or a full provider:model key ("openai:gpt-5.4").

This complements ProviderProfile, which controls the model-construction phase (e.g. init_chat_model kwargs, pre-init side effects). Concerns that shape how the model is built belong in ProviderProfile; concerns that shape how the agent runs belong here.

For YAML/JSON-backed profiles, use HarnessProfileConfig, which contains only the declarative subset and can be passed directly to register_harness_profile.

The extra_middleware field expects langchain.agents.middleware.types.AgentMiddleware instances or a factory returning a sequence of them.

Declarative harness-profile config for YAML/JSON-backed profiles.

A HarnessProfileConfig contains the file-friendly subset of harness settings: plain strings, bools, lists, and nested dicts that can be loaded from YAML or JSON. For in-code/runtime-only adjustments such as extra_middleware or class-form excluded_middleware, use HarnessProfile instead.

Config objects may be passed directly to register_harness_profile; the helper converts them to runtime HarnessProfile objects automatically.

Declarative configuration for constructing a chat model.

A ProviderProfile describes provider- or model-specific kwargs, pre-initialization side effects, and runtime-derived kwargs that should be applied when resolve_model turns a string spec (e.g. "openai:gpt-5.4") into a BaseChatModel. Profiles are registered via register_provider_profile under a provider key ("openai") or a full provider:model key ("openai:gpt-5.4").

Profiles handle model-construction concerns only — things that shape how init_chat_model assembles the client instance. Typical examples: constructor kwargs like use_responses_api, temperature, max_tokens, or base_url; provider-specific headers such as OpenRouter app attribution; pre-construction checks like minimum-version enforcement; and env-var-aware defaults.

Runtime and harness behavior — system-prompt assembly, tool description overrides, excluded tools, extra middleware, general-purpose subagent configuration — belongs in HarnessProfile, the separate harness profile system consumed by create_deep_agent, not here.

Register a harness profile for a provider or specific model.

Accepts a runtime HarnessProfile or converts a declarative HarnessProfileConfig at registration time.

Register under a provider name to set defaults for its models, or under provider:model to customize one model. Model-specific settings inherit provider defaults, with explicit fields replacing or extending them.

For example, exclude a tool for a hypothetical provider's models, then customize the response length for one model:

from deepagents import HarnessProfile, register_harness_profile

register_harness_profile(
    "my_provider",
    HarnessProfile(
        excluded_tools=frozenset({"execute"}),
        system_prompt_suffix="Respond in under 500 words.",
    ),
)
register_harness_profile(
    "my_provider:my-model:tag",
    HarnessProfile(system_prompt_suffix="Respond in under 100 words."),
)

An agent using my_provider:my-model:tag excludes execute and receives the 100-word prompt suffix. Other models from my_provider exclude execute and receive the 500-word suffix.

Register profiles before calling create_deep_agent. Using the hypothetical provider above, you can pass a model string or construct the model yourself:

from langchain.chat_models import init_chat_model

from deepagents import create_deep_agent

# Deep Agents constructs the model from a string.
agent = create_deep_agent(model="my_provider:my-model:tag")

# Or construct a model object first, then pass it to Deep Agents.
model = init_chat_model("my-model:tag", model_provider="my_provider")
agent = create_deep_agent(model=model)

For the model object, Deep Agents looks up the harness profile using the provider and model identifier reported by that object. If it reports my_provider and my-model:tag, it matches the same registration above.

Re-registering merges with the existing profile: new values override conflicts and unspecified fields remain. Continuing the example, exclude one more tool:

register_harness_profile(
    "my_provider:my-model:tag",
    HarnessProfile(excluded_tools=frozenset({"grep"})),
)

An agent created afterward with this model excludes both execute and grep and still receives the 100-word prompt suffix.

Deep Agents also ships built-in profiles: default harness settings registered automatically for selected models. Registering under one of those keys customizes the shipped settings using the same merge rules.

Excluded-tool sets union, middleware sequences merge by type, and general_purpose_subagent settings merge field-wise.

See the Profiles guide for registration workflows and configuration files.

Register a ProviderProfile for a provider or specific model.

Register under a provider name to set defaults for its models, or under provider:model to customize one model. Model-specific settings override conflicting provider defaults and inherit the remaining settings.

For example, set defaults for a hypothetical provider, then lower the temperature for one model:

from deepagents import ProviderProfile, register_provider_profile

register_provider_profile(
    "my_provider",
    ProviderProfile(init_kwargs={"temperature": 0.7, "timeout": 30}),
)
register_provider_profile(
    "my_provider:my-model:tag",
    ProviderProfile(init_kwargs={"temperature": 0}),
)

When Deep Agents constructs my_provider:my-model:tag, the profile supplies temperature=0 and timeout=30. Other models from my_provider receive temperature=0.7 and timeout=30. The model identifier is my-model:tag; only the first colon separates it from the provider.

Register profiles before constructing the agent. Passing a model instance to create_deep_agent leaves its construction settings unchanged; see register_harness_profile for examples of both forms.

Re-registering merges with the existing profile: new values override conflicts and unspecified fields remain. Continuing the example, give this model a longer timeout:

register_provider_profile(
    "my_provider:my-model:tag",
    ProviderProfile(init_kwargs={"timeout": 60}),
)

Future construction of this model uses temperature=0 and timeout=60; other models still use the provider's defaults.

Deep Agents also ships built-in profiles: model-construction defaults registered automatically for selected providers. Registering under one of those keys customizes the shipped settings using the same merge rules.

pre_init callables run existing first, then new. Both init_kwargs_factory callables run in that order too, with the new factory's output winning on shared keys.

See the Profiles guide for registration workflows and configuration files.

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.

Public beta APIs for model and harness profiles.

Profiles let Deep Agents tailor behavior to a specific provider or model spec across two orthogonal phases:

• Provider profiles (ProviderProfile) control the model-construction phase. They declare how resolve_model builds a chat model — init_chat_model kwargs, pre-initialization side effects, and kwargs derived from runtime state (e.g. environment variables).
• Harness profiles (HarnessProfile, HarnessProfileConfig) control the runtime phase. They declare how create_deep_agent shapes the agent after the model is built — prompt assembly, tool visibility, middleware, and default subagent behavior.

Both kinds live in keyed registries that accept a provider or provider:model key. Registration helpers (register_provider_profile, register_harness_profile) are additive: re-registering under an existing key merges on top of the prior registration rather than replacing it.

Directory layout:

• provider/ — ProviderProfile API (provider_profiles.py) plus built-in provider modules (e.g. _openai, _openrouter).
• harness/ — HarnessProfile API (harness_profiles.py) plus built-in harness modules for frontier model specs (e.g. _anthropic_sonnet_4_6, _openai_codex).
• _builtin_profiles.py — bootstrap that registers built-in profiles and loads third-party plugins (via importlib.metadata entry points) lazily on first profile-registry access, so importing this package stays cheap.
• _keys.py — shared validation and lookup helpers for the provider / provider:model registry keys used by both registries.

Middleware for the Deep Agents agent.

Overview

The LLM receives tools through two paths:

1. SDK middleware (this package) -- tools, system-prompt injection, and request interception that any SDK consumer gets automatically.
2. Consumer-provided tools -- plain callable functions passed via the tools parameter to create_deep_agent(). The CLI uses this path for lightweight, consumer-specific tools.

Both are merged by create_deep_agent() into the final tool set the LLM sees.

Why middleware instead of plain tools?

Middleware subclasses AgentMiddleware, overriding its wrap_model_call() hook that intercepts every LLM request before it is sent. This lets middleware:

• Filter tools dynamically -- e.g. FilesystemMiddleware removes the execute tool at call-time when the resolved backend doesn't support it.
• Inject system-prompt context -- e.g. MemoryMiddleware and SkillsMiddleware inject relevant instructions into the system message on every call so the LLM knows how to use the tools they provide.
• Transform messages -- e.g. SummarizationMiddleware counts tokens, truncates old tool arguments, and replaces history with summaries when the context window fills up.
• Maintain cross-turn state -- middleware can read/write a typed state dict that persists across agent turns (e.g. summarization events).

A plain tool function in a tools=[] list cannot do any of this -- it is only invoked by the LLM, not before the LLM call.

When to use each path

Use middleware when the tool needs to:

• Modify the system prompt or tool list per-call
• Track state across turns
• Be available to all SDK consumers (not just the CLI)

Use a plain tool when:

• The function is stateless and self-contained
• No system-prompt or request modification is needed
• The tool is specific to a single consumer (e.g. CLI-only)

Memory backends for pluggable file storage.