Anthropic Middleware¶

Reference docs

This page contains reference documentation for Anthropic Middleware. See the docs for conceptual guides, tutorials, and examples on using Anthropic Middleware.

Provider-specific middleware for Anthropic's Claude models:

CLASS	DESCRIPTION
`AnthropicPromptCachingMiddleware`	Reduce costs by caching repetitive prompt prefixes
`ClaudeBashToolMiddleware`	Execute Claude's native bash tool with local command execution
`StateClaudeTextEditorMiddleware`	Provide Claude's text editor tool for state-based file editing
`FilesystemClaudeTextEditorMiddleware`	Provide Claude's text editor tool for filesystem-based file editing
`StateClaudeMemoryMiddleware`	Provide Claude's memory tool for state-based persistent agent memory
`FilesystemClaudeMemoryMiddleware`	Provide Claude's memory tool for filesystem-based persistent agent memory
`StateFileSearchMiddleware`	Search tools for state-based file systems

AnthropicPromptCachingMiddleware ¶

AnthropicPromptCachingMiddleware(
    type: Literal["ephemeral"] = "ephemeral",
    ttl: Literal["5m", "1h"] = "5m",
    min_messages_to_cache: int = 0,
    unsupported_model_behavior: Literal["ignore", "warn", "raise"] = "warn",
)

Bases: AgentMiddleware

Prompt Caching Middleware.

Optimizes API usage by caching conversation prefixes for Anthropic models.

Requires both langchain and langchain-anthropic packages to be installed.

Learn more about Anthropic prompt caching here.

Initialize the middleware with cache control settings.

PARAMETER	DESCRIPTION
`type`	The type of cache to use, only `'ephemeral'` is supported. TYPE: `Literal['ephemeral']` DEFAULT: `'ephemeral'`
`ttl`	The time to live for the cache, only `'5m'` and `'1h'` are supported. TYPE: `Literal['5m', '1h']` DEFAULT: `'5m'`
`min_messages_to_cache`	The minimum number of messages until the cache is used. TYPE: `int` DEFAULT: `0`
`unsupported_model_behavior`	The behavior to take when an unsupported model is used. `'ignore'` will ignore the unsupported model and continue without caching. `'warn'` will warn the user and continue without caching. `'raise'` will raise an error and stop the agent. TYPE: `Literal['ignore', 'warn', 'raise']` DEFAULT: `'warn'`

ClaudeBashToolMiddleware ¶

ClaudeBashToolMiddleware(
    workspace_root: str | None = None,
    *,
    startup_commands: tuple[str, ...] | list[str] | str | None = None,
    shutdown_commands: tuple[str, ...] | list[str] | str | None = None,
    execution_policy: Any | None = None,
    redaction_rules: tuple[Any, ...] | list[Any] | None = None,
    tool_description: str | None = None,
    env: dict[str, Any] | None = None,
)

Bases: ShellToolMiddleware

Middleware that exposes Anthropic's native bash tool to models.

Initialize middleware for Claude's native bash tool.

PARAMETER	DESCRIPTION
`workspace_root`	Base directory for the shell session. If omitted, a temporary directory is created. TYPE: `str \| None` DEFAULT: `None`
`startup_commands`	Optional commands executed after the session starts. TYPE: `tuple[str, ...] \| list[str] \| str \| None` DEFAULT: `None`
`shutdown_commands`	Optional commands executed before session shutdown. TYPE: `tuple[str, ...] \| list[str] \| str \| None` DEFAULT: `None`
`execution_policy`	Execution policy controlling timeouts and limits. TYPE: `Any \| None` DEFAULT: `None`
`redaction_rules`	Optional redaction rules to sanitize output. TYPE: `tuple[Any, ...] \| list[Any] \| None` DEFAULT: `None`
`tool_description`	Optional override for tool description. TYPE: `str \| None` DEFAULT: `None`
`env`	Optional environment variables for the shell session. TYPE: `dict[str, Any] \| None` DEFAULT: `None`

StateClaudeTextEditorMiddleware ¶

StateClaudeTextEditorMiddleware(*, allowed_path_prefixes: Sequence[str] | None = None)

Bases: _StateClaudeFileToolMiddleware

State-based text editor tool middleware.

Provides Anthropic's text_editor tool using LangGraph state for storage. Files persist for the conversation thread.

Example

from langchain.agents import create_agent
from langchain.agents.middleware import StateTextEditorToolMiddleware

agent = create_agent(
    model=model,
    tools=[],
    middleware=[StateTextEditorToolMiddleware()],
)

Initialize the text editor middleware.

PARAMETER	DESCRIPTION
`allowed_path_prefixes`	Optional list of allowed path prefixes. If specified, only paths starting with these prefixes are allowed. TYPE: `Sequence[str] \| None` DEFAULT: `None`

FilesystemClaudeTextEditorMiddleware ¶

FilesystemClaudeTextEditorMiddleware(
    *,
    root_path: str,
    allowed_prefixes: list[str] | None = None,
    max_file_size_mb: int = 10,
)

Bases: _FilesystemClaudeFileToolMiddleware

Filesystem-based text editor tool middleware.

Provides Anthropic's text_editor tool using local filesystem for storage. User handles persistence via volumes, git, or other mechanisms.

Example

from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemTextEditorToolMiddleware

agent = create_agent(
    model=model,
    tools=[],
    middleware=[FilesystemTextEditorToolMiddleware(root_path="/workspace")],
)

Initialize the text editor middleware.

PARAMETER	DESCRIPTION
`root_path`	Root directory for file operations. TYPE: `str`
`allowed_prefixes`	Optional list of allowed virtual path prefixes. Defaults to `['/']`. TYPE: `list[str] \| None` DEFAULT: `None`
`max_file_size_mb`	Maximum file size in MB Defaults to `10`. TYPE: `int` DEFAULT: `10`

StateClaudeMemoryMiddleware ¶

StateClaudeMemoryMiddleware(
    *,
    allowed_path_prefixes: Sequence[str] | None = None,
    system_prompt: str = MEMORY_SYSTEM_PROMPT,
)

Bases: _StateClaudeFileToolMiddleware

State-based memory tool middleware.

Provides Anthropic's memory tool using LangGraph state for storage. Files persist for the conversation thread.

Enforces /memories prefix and injects Anthropic's recommended system prompt.

Example

from langchain.agents import create_agent
from langchain.agents.middleware import StateMemoryToolMiddleware

agent = create_agent(
    model=model,
    tools=[],
    middleware=[StateMemoryToolMiddleware()],
)

Initialize the memory middleware.

PARAMETER	DESCRIPTION
`allowed_path_prefixes`	Optional list of allowed path prefixes. Defaults to `['/memories']`. TYPE: `Sequence[str] \| None` DEFAULT: `None`
`system_prompt`	System prompt to inject. Defaults to Anthropic's recommended memory prompt. TYPE: `str` DEFAULT: `MEMORY_SYSTEM_PROMPT`

FilesystemClaudeMemoryMiddleware ¶

FilesystemClaudeMemoryMiddleware(
    *,
    root_path: str,
    allowed_prefixes: list[str] | None = None,
    max_file_size_mb: int = 10,
    system_prompt: str = MEMORY_SYSTEM_PROMPT,
)

Bases: _FilesystemClaudeFileToolMiddleware

Filesystem-based memory tool middleware.

Provides Anthropic's memory tool using local filesystem for storage. User handles persistence via volumes, git, or other mechanisms.

Enforces /memories prefix and injects Anthropic's recommended system prompt.

Example

from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemMemoryToolMiddleware

agent = create_agent(
    model=model,
    tools=[],
    middleware=[FilesystemMemoryToolMiddleware(root_path="/workspace")],
)

Initialize the memory middleware.

PARAMETER	DESCRIPTION
`root_path`	Root directory for file operations. TYPE: `str`
`allowed_prefixes`	Optional list of allowed virtual path prefixes. Defaults to `['/memories']`. TYPE: `list[str] \| None` DEFAULT: `None`
`max_file_size_mb`	Maximum file size in MB Defaults to `10`. TYPE: `int` DEFAULT: `10`
`system_prompt`	System prompt to inject. Defaults to Anthropic's recommended memory prompt. TYPE: `str` DEFAULT: `MEMORY_SYSTEM_PROMPT`

StateFileSearchMiddleware ¶

StateFileSearchMiddleware(*, state_key: str = 'text_editor_files')

Bases: AgentMiddleware

Provides Glob and Grep search over state-based files.

This middleware adds two tools that search through virtual files in state:

Glob: Fast file pattern matching by file path
Grep: Fast content search using regular expressions

Example

from langchain.agents import create_agent
from langchain.agents.middleware import (
    StateTextEditorToolMiddleware,
    StateFileSearchMiddleware,
)

agent = create_agent(
    model=model,
    tools=[],
    middleware=[
        StateTextEditorToolMiddleware(),
        StateFileSearchMiddleware(),
    ],
)

Initialize the search middleware.

PARAMETER	DESCRIPTION
`state_key`	State key to search Use `'memory_files'` to search memory tool files. TYPE: `str` DEFAULT: `'text_editor_files'`