Skip to main content

Customize Deep Agents

还没翻译译自英文（docs.langchain.com）本页 164 段都还没译

Build the harness around your goal. create_deep_agent gives you a production-ready foundation: connect it to your data, shape its behavior, and add the capabilities your use case needs.

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    system_prompt="You are a helpful assistant.",
    tools=[search, fetch_url],
    memory=["./AGENTS.md"],
    skills=["./skills/"],
)
ParameterWhat it does
model=Which model to use
system_prompt=Custom instructions for the agent
tools=Domain tools the agent can call
memory=AGENTS.md files loaded at startup
skills=Skills directory for on-demand knowledge
backend=Filesystem backend (StateBackend by default)
permissions=Path-level access control for the filesystem
subagents=Custom subagents for delegated tasks
middleware=Extra middleware merged into the Deep Agents stack; an instance whose .name matches a built-in entry replaces it in place, anything else lands after the last core middleware entry and before the profile, prompt-caching, and memory
interrupt_on=Pause before tool calls for human approval
response_format=Structured output schema
state_schema=Custom graph state schema
context_schema=Per-run runtime context schema (user IDs, API keys, feature flags)
profilesPer-model defaults as a reusable bundle

For the full parameter list, see the create_deep_agent API reference. To compose a fully custom harness from scratch, see Configure the harness or follow the step-by-step Build a deep agent from scratch guide.

Tip

As you add tools, subagents, and backends, use LangSmith to trace how each piece behaves together. Follow the observability quickstart to get set up, and see Going to production for deployment on LangSmith.

We recommend you also set up LangSmith Engine, which monitors your traces, detects issues, and proposes fixes.

Model

Pass a model string in provider:model format, or an initialized model instance. See supported models for all providers and suggested models for tested recommendations.

Tip

Use the provider:model format (for example openai:gpt-5.5) to quickly switch between models.

OpenAIAnthropicAzureGoogle GeminiAWS BedrockHuggingFaceOther

👉 Read the OpenAI chat model integration docs

pipuv

pip install -U "langchain[openai]"

default parametersinit_chat_modelmodel class

import os
from deepagents import create_deep_agent

os.environ["OPENAI_API_KEY"] = "sk-..."

agent = create_deep_agent(model="openai:gpt-5.5")
# this calls init_chat_model for the specified model with default parameters
# to use specific model parameters, use init_chat_model directly

Tip

Chat models automatically retry transient API failures (with exponential backoff). For defaults, limits, and code samples for tuning max_retries / timeout live on the LangChain Models page.

Tools

In addition to built-in tools for file management and subagent spawning, you can provide custom tools:

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])


def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )


agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[internet_search],
)

MCP tools

Tip

Deep Agents fully support Model Context Protocol (MCP) tools. You can load tools from any MCP server—databases, APIs, file systems, and more—and pass them directly to create_deep_agent.

Install LangChain with the mcp extra to connect to MCP servers:

pip install "langchain[mcp]"

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

import asyncio

from deepagents import create_deep_agent
from langchain.mcp import MCPAdapter


async def main():
    config = {"mcpServers": {"my_server": {"url": "http://localhost:8000/mcp"}}}
    async with MCPAdapter(config) as adapter:
        tools = await adapter.list_tools()
        agent = create_deep_agent(
            model="google_genai:gemini-3.6-flash",
            tools=tools,
        )
        await agent.ainvoke(
            {
                "messages": [
                    {"role": "user", "content": "Use the MCP server to help me."}
                ]
            },
            config={"configurable": {"thread_id": "1"}},
        )

For detailed configuration options including stdio servers, OAuth authentication, tool filtering, and stateful sessions, see the full MCP guide.

System prompt

Pass system_prompt= to give the agent your own instructions:

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

from deepagents import create_deep_agent

research_instructions = """\
You are an expert researcher. Your job is to conduct \
thorough research, and then write a polished report. \
"""

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    system_prompt=research_instructions,
)

Note

Besides a string, the main agent also accepts a SystemMessage with structured content blocks; Deep Agents preserve those blocks (subagent dictionary specs remain strings).

Middleware

Deep Agents support any middleware, including the built-in middleware listed below, prebuilt middleware from LangChain, provider-specific middleware, and custom middleware you write yourself.

Pass middleware to the middleware argument of create_deep_agent. Each instance is merged into the Deep Agents stack by matching its .name against built-in entries already in the stack: a match replaces that instance in place, and anything that does not match is inserted after PatchToolCallsMiddleware. See Override a default middleware instance.

Deep Agents stack

create_deep_agent builds middleware in a fixed order. The bare stack is what you get with only a model. The full stack is the complete assembly order, including slots that appear only when you pass optional arguments or when the resolved harness profile contributes them.

Bare stack

With only a model (no other optional arguments), the main agent typically includes:

  1. FilesystemMiddleware
  2. SubAgentMiddleware (because the general-purpose subagent is auto-added unless a harness profile disables it)
  3. SummarizationMiddleware
  4. PatchToolCallsMiddleware
  5. Prompt caching middleware (always registered; each entry no-ops on models it does not support)
  6. Harness profile extras and excluded-tool filtering, if the resolved model profile defines them

Full stack

From first to last:

  1. FilesystemMiddleware: Handles file system operations such as reading, writing, and navigating directories. When you pass permissions, filesystem permissions enforcement is included here so it can evaluate every tool the agent might call.

  2. SubAgentMiddleware: Only when at least one synchronous subagent is available. Spawns and coordinates subagents for delegating tasks. Included in the bare stack because the general-purpose subagent is auto-added by default; omit it by disabling that subagent and passing no synchronous subagents. See Running without subagents.

  3. SummarizationMiddleware: Condenses message history to stay within context limits when conversations grow long (via create_summarization_middleware).

  4. PatchToolCallsMiddleware: Repairs dangling tool calls in message history when a run resumes after an interruption or receives malformed tool-call arguments. Runs before Anthropic prompt caching and the tail stack below.

  5. AsyncSubAgentMiddleware: Only when you configure async subagents.

  6. Your middleware argument: Optional middleware you pass as the middleware argument is merged after Patch but before the rest of the stack. An instance whose .name matches one of the built-in entries above replaces that instance in place instead of duplicating it; anything else lands here. See Override a default middleware instance.

  7. Harness profile extras: Provider-specific middleware from the resolved model profile, if any.

  8. SkillsMiddleware: Only when you pass skills. Runs after your middleware and directly before prompt caching, so it sees the summarized conversation and the model that is actually called. Passing a middleware named SkillsMiddleware replaces it in place.

  9. Prompt caching (AnthropicPromptCachingMiddleware and BedrockPromptCachingMiddleware): Both are always registered and run after Patch and after your middleware so the cached prefix matches what is actually sent to the model. Each no-ops on models it does not support (unsupported_model_behavior="ignore"), so the Anthropic middleware applies on Anthropic models and the Bedrock middleware on AWS Bedrock models with cache support.

  10. MemoryMiddleware: Only when you pass memory.

    Note

    MemoryMiddleware is placed after profile extras and the prompt caching middleware so updates to injected memory are less likely to invalidate the cache prefix. The same ordering concern is called out in the create_deep_agent implementation comments.

  11. HumanInTheLoopMiddleware: Only when you pass interrupt_on. Pauses for human approval or input at configured tool calls.

  12. Excluded-tool filtering: When the harness profile lists excluded tools, middleware removes those tools from the agent.

Synchronous subagent stack

The built-in general-purpose subagent and each declarative synchronous SubAgent graph use a stack that create_deep_agent builds in code. It matches the main agent in broad shape (filesystem, summarization, Patch, profile extras, skills, Anthropic and Bedrock caching, optional permissions), except that there is no SubAgentMiddleware inside a subagent graph (only the parent agent exposes the task tool).

When a declarative subagent sets interrupt_on, that value is forwarded to create_agent for the subagent, which wires up human-in-the-loop handling for the configured tool calls.

Prebuilt middleware

LangChain exposes additional prebuilt middleware that let you add-on various features, such as retries, fallbacks, or PII detection. See Prebuilt middleware for more.

The deepagents library also exposes create_summarization_tool_middleware, enabling agents to trigger summarization at opportune times—such as between tasks—instead of at fixed token intervals. For more detail, see Summarization.

Provider-specific middleware

For provider-specific middleware that is optimized for specific LLM providers, see Middleware integrations.

Custom middleware

You can provide additional middleware to extend functionality, add tools, or implement custom hooks:

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

from langchain.agents.middleware import wrap_tool_call
from langchain.tools import tool
from deepagents import create_deep_agent


@tool
def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is sunny."


call_count = [0]  # Use list to allow modification in nested function


@wrap_tool_call
def log_tool_calls(request, handler):
    """Intercept and log every tool call - demonstrates cross-cutting concern."""
    call_count[0] += 1
    tool_name = request.name if hasattr(request, "name") else str(request)

    print(f"[Middleware] Tool call #{call_count[0]}: {tool_name}")
    print(f"[Middleware] Arguments: {request.args if hasattr(request, 'args') else 'N/A'}")

    # Execute the tool call
    result = handler(request)

    # Log the result
    print(f"[Middleware] Tool call #{call_count[0]} completed")

    return result


agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[get_weather],
    middleware=[log_tool_calls],
)

Warning

Do not mutate attributes after initialization

If you need to track values across hook invocations (for example, counters or accumulated data), use graph state. Graph state is scoped to a thread by design, so updates are safe under concurrency.

Do this:

from langchain.agents.middleware import AgentMiddleware


class CustomMiddleware(AgentMiddleware):
    def __init__(self):
        pass

    def before_agent(self, state, runtime):
        return {"x": state.get("x", 0) + 1}  # Update graph state instead

Do not do this:

class CustomMiddlewareBad(AgentMiddleware):
    def __init__(self):
        self.x = 1

    def before_agent(self, state, runtime):
        self.x += 1  # Mutation causes race conditions

Mutation in place, such as modifying self.x in before_agent or changing other shared values in hooks, can lead to subtle bugs and race conditions because many operations run concurrently (subagents, parallel tools, and parallel invocations on different threads).

For full details on extending state with custom properties, see Custom middleware - Custom state schema.

If you must use mutation in custom middleware, consider what happens when subagents, parallel tools, or concurrent agent invocations run at the same time.

Override a default middleware instance

Note

Overriding a default middleware by matching .name requires deepagents>=0.7.

Pass a middleware instance whose .name matches an entry in the Deep Agents stack, such as SummarizationMiddleware, to replace that built-in instance in place instead of appending a duplicate. Any middleware you pass whose .name does not match a built-in entry is not replaced, it lands after the last core middleware entry and before the profile, prompt-caching, and memory. See Full stack for the complete ordering.

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware import SummarizationMiddleware

backend = StateBackend()
model = "openai:gpt-5.5"

custom_summarization = SummarizationMiddleware(
    model=model,
    backend=backend,
    summary_prompt="Your custom summary prompt here.",
)

agent = create_deep_agent(
    model=model,
    middleware=[custom_summarization],  # replaces the default SummarizationMiddleware
)

Note

An override replaces the default middleware instance, it is not merged with it. That means your replacement must be fully configured with any settings it needs. This is especially important for FilesystemMiddleware: if you override it, you must pass the backend (and permissions, if applicable) directly to your custom instance, since it won't inherit the backend= and permissions= passed to create_deep_agent(). To restrict the available filesystem tools, pass a tools allowlist to your custom FilesystemMiddleware instance; see Virtual filesystem access for the "Restricting filesystem tools" example.

The general-purpose subagent, which Deep Agents adds automatically, inherits overrides for its default middleware from the main agent, without carrying over middleware that's specific to the main agent.

Declarative subagents defined via subagents= do not inherit the main agent's middleware customization. Pass the override directly in that subagent's own middleware field to apply it there; that field is matched against the synchronous subagent stack, the same way middleware= is matched against the main agent's.

Examples

Interpreters

Use interpreters to add an eval tool that runs JavaScript in a scoped QuickJS runtime. Interpreters are useful when the agent needs to compose tools programmatically, batch work, handle errors in code, or transform structured data without a full shell environment.

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[CodeInterpreterMiddleware()],
)

For setup, programmatic tool calling, subagent orchestration, and limits, see Interpreters.

Subagents

To isolate detailed work and avoid context bloat, use subagents:

import os
from typing import Literal

from deepagents import create_deep_agent
from tavily import TavilyClient

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])


def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )


research_subagent = {
    "name": "research-agent",
    "description": "Used to research more in depth questions",
    "system_prompt": "You are a great researcher",
    "tools": [internet_search],
    "model": "openai:gpt-5.5",  # Optional override, defaults to main agent model
}
subagents = [research_subagent]

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    subagents=subagents,
)

For more information, see Subagents.

Backends

Tools for a deep agent can make use of virtual file systems to store, access, and edit files. By default, deep agents use a StateBackend.

If you are using skills or memory, you must add the expected skill or memory files to the backend before creating the agent.

StateBackendFilesystemBackendLocalShellBackendStoreBackendContextHubBackendCompositeBackend

A thread-scoped filesystem backend stored in langgraph state.

Files persist across turns within a thread (via your checkpointer) and are not shared across threads.

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# By default we provide a StateBackend
agent = create_deep_agent(model="google_genai:gemini-3.6-flash")

# Under the hood, it looks like
agent2 = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=StateBackend(),
)

For more information, see Backends.

Sandboxes

Sandboxes are specialized backends that run agent code in an isolated environment with their own filesystem and an execute tool for shell commands. Use a sandbox backend when you want your deep agent to write files, install dependencies, and run commands without changing anything on your local machine.

You configure sandboxes by passing a sandbox backend to backend when creating your deep agent:

LangSmithDaytonaE2BModalRunloopVercel

pipuv

pip install langsmith

from deepagents import create_deep_agent
from deepagents.backends import LangSmithSandbox
from langchain_anthropic import ChatAnthropic
from langsmith.sandbox import SandboxClient

client = SandboxClient()
ls_sandbox = client.create_sandbox()
backend = LangSmithSandbox(sandbox=ls_sandbox)

agent = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    system_prompt="You are a Python coding assistant with sandbox access.",
    backend=backend,
)
try:
    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "Create a small Python package and run pytest",
                }
            ]
        }
    )
finally:
    client.delete_sandbox(ls_sandbox.name)

For more information, see Sandboxes.

Human-in-the-loop

Some tool operations may be sensitive and require human approval before execution. You can configure the approval for each tool:

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

from langchain.tools import tool
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver


@tool
def remove_file(path: str) -> str:
    """Delete a file from the filesystem."""
    return f"Deleted {path}"


@tool
def fetch_file(path: str) -> str:
    """Read a file from the filesystem."""
    return f"Contents of {path}"


@tool
def notify_email(to: str, subject: str, body: str) -> str:
    """Send an email."""
    return f"Sent email to {to}"


# Checkpointer is REQUIRED for human-in-the-loop
checkpointer = MemorySaver()

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[remove_file, fetch_file, notify_email],
    interrupt_on={
        "remove_file": True,  # Default: approve, edit, reject, respond
        "fetch_file": False,  # No interrupts needed
        "notify_email": {"allowed_decisions": ["approve", "reject"]},  # No editing
    },
    checkpointer=checkpointer,  # Required!
)

You can configure interrupt for agents and subagents on tool call as well as from within tool calls. For more information, see Human-in-the-loop.

Skills

You can use skills to provide your deep agent with new capabilities and expertise. While tools tend to cover lower level functionality like native file system actions, skills can contain detailed instructions on how to complete tasks, reference info, and other assets, such as templates. These files are only loaded by the agent when the agent has determined that the skill is useful for the current prompt. This progressive disclosure reduces the amount of tokens and context the agent has to consider upon startup.

For example skills, see Deep Agents example skills.

To add skills to your deep agent, pass them as an argument to create_deep_agent:

StateBackendStoreBackendFilesystemBackend

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

from urllib.request import urlopen
from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.backends.utils import create_file_data
from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()
backend = StateBackend()

skill_url = "https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/code/examples/skills/langgraph-docs/SKILL.md"
with urlopen(skill_url) as response:
    skill_content = response.read().decode('utf-8')

skills_files = {
    "/skills/langgraph-docs/SKILL.md": create_file_data(skill_content),
}

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=backend,
    skills=["/skills/"],
    checkpointer=checkpointer,
)

result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "What is langgraph?"}],
        # Seed the default StateBackend's in-state filesystem (virtual paths must start with "/").
        "files": skills_files,
    },
    config={"configurable": {"thread_id": "12345"}},
)

Memory

Use AGENTS.md files to provide extra context to your deep agent.

Tip

To generate a repository wiki that coding agents discover through AGENTS.md, see OpenWiki.

You can pass one or more file paths to the memory parameter when creating your deep agent:

StateBackendStoreBackendFilesystemBackend

GoogleOpenAIAnthropicOpenRouterFireworksBasetenOllama

from urllib.request import urlopen

from deepagents import create_deep_agent
from deepagents.backends.utils import create_file_data
from langgraph.checkpoint.memory import MemorySaver

with urlopen(
    "https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/examples/text-to-sql-agent/AGENTS.md"
) as response:
    agents_md = response.read().decode("utf-8")
checkpointer = MemorySaver()

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    memory=[
        "/AGENTS.md"
    ],
    checkpointer=checkpointer,
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Please tell me what's in your memory files.",
            }
        ],
        # Seed the default StateBackend's in-state filesystem (virtual paths must start with "/").
        "files": {"/AGENTS.md": create_file_data(agents_md)},
    },
    config={"configurable": {"thread_id": "123456"}},
)

Profiles

A harness profile is a reusable bundle of per-model configuration that create_deep_agent applies automatically when the matching model is selected. Profiles are the right tool when you want behaviour that follows the model—not the call site—such as a system prompt suffix tuned for Claude's instruction style, tool descriptions rewritten for GPT, or extra middleware that only makes sense with a specific provider.

A single profile can carry: a custom base system prompt (base_system_prompt), an appended suffix (system_prompt_suffix), tool description overrides, tools or middleware to exclude, additional middleware to inject, and edits to the auto-added general-purpose subagent.

from deepagents import HarnessProfile, register_harness_profile

# Append a system-prompt suffix whenever gpt-5.5 is selected.
register_harness_profile(
    "openai:gpt-5.5",
    HarnessProfile(system_prompt_suffix="Respond in under 100 words."),
)

See Profiles for registration keys, merge semantics, and plugin packaging. A narrower companion API, provider profiles, packages model-construction arguments (API keys, timeouts, retry settings) for a provider.

Structured output

Deep Agents support structured output. You can set a desired structured output schema by passing it as the response_format argument to the call to create_deep_agent(). When the model generates the structured data, it's captured, validated, and returned in the 'structured_response' key of the deep agent's state.

import os
from typing import Literal

from pydantic import BaseModel, Field
from tavily import TavilyClient

from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])


def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )


class WeatherReport(BaseModel):
    """A structured weather report with current conditions and forecast."""
    location: str = Field(description="The location for this weather report")
    temperature: float = Field(description="Current temperature in Celsius")
    condition: str = Field(
        description="Current weather condition (e.g., sunny, cloudy, rainy)"
    )
    humidity: int = Field(description="Humidity percentage")
    wind_speed: float = Field(description="Wind speed in km/h")
    forecast: str = Field(description="Brief forecast for the next 24 hours")


agent = create_deep_agent(
    model=model,
    response_format=WeatherReport,
    tools=[internet_search],
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "What's the weather like in San Francisco?",
            }
        ]
    }
)

print(result["structured_response"])
# location='San Francisco, California' temperature=18.3 condition='Sunny' humidity=48 wind_speed=7.6 forecast='Pleasant sunny conditions expected to continue with temperatures around 64°F (18°C) during the day, dropping to around 52°F (11°C) at night. Clear skies with minimal precipitation expected.'

View example trace

Open a public LangSmith run for this example.

For more information and examples, see response format.

Advanced

create_deep_agent pre-assembles a middleware stack on top of create_agent. To build a fully custom agent—choosing exactly which capabilities to include—see Configure the harness.

AI 翻译查看英文原文