> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-provid-1764959672-4860de7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic middleware

Middleware specifically designed for Anthropic's Claude models. Learn more about [middleware](/oss/python/langchain/middleware/overview).

| Middleware                        | Description                                                    |
| --------------------------------- | -------------------------------------------------------------- |
| [Prompt caching](#prompt-caching) | Reduce costs by caching repetitive prompt prefixes             |
| [Bash tool](#bash-tool)           | Execute Claude's native bash tool with local command execution |
| [Text editor](#text-editor)       | Provide Claude's text editor tool for file editing             |
| [Memory](#memory)                 | Provide Claude's memory tool for persistent agent memory       |
| [File search](#file-search)       | Search tools for state-based file systems                      |

## Prompt caching

Reduce costs and latency by caching static or repetitive prompt content (like system prompts, tool definitions, and conversation history) on Anthropic's servers. This middleware implements a **conversational caching strategy** that places cache breakpoints after the most recent message, allowing the entire conversation history (including the latest user message) to be cached and reused in subsequent API calls. Prompt caching is useful for the following:

* Applications with long, static system prompts that don't change between requests
* Agents with many tool definitions that remain constant across invocations
* Conversations where early message history is reused across multiple turns
* High-volume deployments where reducing API costs and latency is critical

<Info>
  Learn more about [Anthropic prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations) strategies and limitations.
</Info>

**API reference:** [`AnthropicPromptCachingMiddleware`](https://reference.langchain.com/python/integrations/langchain_anthropic/middleware/#langchain_anthropic.middleware.AnthropicPromptCachingMiddleware)

```python theme={null}
from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import AnthropicPromptCachingMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
    system_prompt="<Your long system prompt here>",
    middleware=[AnthropicPromptCachingMiddleware(ttl="5m")],
)
```

<Accordion title="Configuration options">
  <ParamField body="type" type="string" default="ephemeral">
    Cache type. Only `'ephemeral'` is currently supported.
  </ParamField>

  <ParamField body="ttl" type="string" default="5m">
    Time to live for cached content. Valid values: `'5m'` or `'1h'`
  </ParamField>

  <ParamField body="min_messages_to_cache" type="number" default="0">
    Minimum number of messages before caching starts
  </ParamField>

  <ParamField body="unsupported_model_behavior" type="string" default="warn">
    Behavior when using non-Anthropic models. Options: `'ignore'`, `'warn'`, or `'raise'`
  </ParamField>
</Accordion>

<Accordion title="Full example">
  The middleware caches content up to and including the latest message in each request. On subsequent requests within the TTL window (5 minutes or 1 hour), previously seen content is retrieved from cache rather than reprocessed, significantly reducing costs and latency.

  **How it works:**

  1. First request: System prompt, tools, and the user message "Hi, my name is Bob" are sent to the API and cached
  2. Second request: The cached content (system prompt, tools, and first message) is retrieved from cache. Only the new message "What's my name?" needs to be processed, plus the model's response from the first request
  3. This pattern continues for each turn, with each request reusing the cached conversation history

  ```python theme={null}
  from langchain_anthropic import ChatAnthropic
  from langchain_anthropic.middleware import AnthropicPromptCachingMiddleware
  from langchain.agents import create_agent
  from langchain.messages import HumanMessage


  LONG_PROMPT = """
  Please be a helpful assistant.

  <Lots more context ...>
  """

  agent = create_agent(
      model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
      system_prompt=LONG_PROMPT,
      middleware=[AnthropicPromptCachingMiddleware(ttl="5m")],
  )

  # First invocation: Creates cache with system prompt, tools, and "Hi, my name is Bob"
  agent.invoke({"messages": [HumanMessage("Hi, my name is Bob")]})

  # Second invocation: Reuses cached system prompt, tools, and previous messages
  # Only processes the new message "What's my name?" and the previous AI response
  agent.invoke({"messages": [HumanMessage("What's my name?")]})
  ```
</Accordion>

## Bash tool

Execute Claude's native `bash_20250124` tool with local command execution. The bash tool middleware is useful for the following:

* Using Claude's built-in bash tool with local execution
* Leveraging Claude's optimized bash tool interface
* Agents that need persistent shell sessions with Anthropic models

<Info>
  This middleware wraps `ShellToolMiddleware` and exposes it as Claude's native bash tool.
</Info>

**API reference:** [`ClaudeBashToolMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.ClaudeBashToolMiddleware)

```python theme={null}
from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import ClaudeBashToolMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
    tools=[],
    middleware=[
        ClaudeBashToolMiddleware(
            workspace_root="/workspace",
        ),
    ],
)
```

<Accordion title="Configuration options">
  `ClaudeBashToolMiddleware` accepts all parameters from [`ShellToolMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.ShellToolMiddleware), including:

  <ParamField body="workspace_root" type="str | Path | None">
    Base directory for the shell session
  </ParamField>

  <ParamField body="startup_commands" type="tuple[str, ...] | list[str] | str | None">
    Commands to run when the session starts
  </ParamField>

  <ParamField body="execution_policy" type="BaseExecutionPolicy | None">
    Execution policy (`HostExecutionPolicy`, `DockerExecutionPolicy`, or `CodexSandboxExecutionPolicy`)
  </ParamField>

  <ParamField body="redaction_rules" type="tuple[RedactionRule, ...] | list[RedactionRule] | None">
    Rules for sanitizing command output
  </ParamField>

  See [Shell tool](/oss/python/langchain/middleware/built-in#shell-tool) for full configuration details.
</Accordion>

<Accordion title="Full example">
  ```python theme={null}
  from langchain_anthropic import ChatAnthropic
  from langchain_anthropic.middleware import ClaudeBashToolMiddleware
  from langchain.agents import create_agent
  from langchain.agents.middleware import DockerExecutionPolicy


  agent = create_agent(
      model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
      tools=[],
      middleware=[
          ClaudeBashToolMiddleware(
              workspace_root="/workspace",
              startup_commands=["pip install requests"],
              execution_policy=DockerExecutionPolicy(
                  image="python:3.11-slim",
              ),
          ),
      ],
  )

  # Claude can now use its native bash tool
  result = agent.invoke({
      "messages": [{"role": "user", "content": "List files in the workspace"}]
  })
  ```
</Accordion>

## Text editor

Provide Claude's text editor tool (`text_editor_20250728`) for file creation and editing. The text editor middleware is useful for the following:

* File-based agent workflows
* Code editing and refactoring tasks
* Multi-file project work
* Agents that need persistent file storage

<Note>
  Available in two variants: **State-based** (files in LangGraph state) and **Filesystem-based** (files on disk).
</Note>

**API reference:** [`StateClaudeTextEditorMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.StateClaudeTextEditorMiddleware), [`FilesystemClaudeTextEditorMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.FilesystemClaudeTextEditorMiddleware)

```python theme={null}
from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import StateClaudeTextEditorMiddleware
from langchain.agents import create_agent

# State-based (files in LangGraph state)
agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
    tools=[],
    middleware=[
        StateClaudeTextEditorMiddleware(),
    ],
)
```

<Accordion title="Configuration options">
  **[`StateClaudeTextEditorMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.StateClaudeTextEditorMiddleware) (state-based)**

  <ParamField body="allowed_path_prefixes" type="Sequence[str] | None">
    Optional list of allowed path prefixes. If specified, only paths starting with these prefixes are allowed.
  </ParamField>

  **[`FilesystemClaudeTextEditorMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.FilesystemClaudeTextEditorMiddleware) (filesystem-based)**

  <ParamField body="root_path" type="str" required>
    Root directory for file operations
  </ParamField>

  <ParamField body="allowed_prefixes" type="list[str] | None">
    Optional list of allowed virtual path prefixes (default: `["/"]`)
  </ParamField>

  <ParamField body="max_file_size_mb" type="int" default="10">
    Maximum file size in MB
  </ParamField>
</Accordion>

<Accordion title="Full example">
  Claude's text editor tool supports the following commands:

  * `view` - View file contents or list directory
  * `create` - Create a new file
  * `str_replace` - Replace string in file
  * `insert` - Insert text at line number
  * `delete` - Delete a file
  * `rename` - Rename/move a file

  ```python theme={null}
  from langchain_anthropic import ChatAnthropic
  from langchain_anthropic.middleware import (
      StateClaudeTextEditorMiddleware,
      FilesystemClaudeTextEditorMiddleware,
  )
  from langchain.agents import create_agent


  # State-based: Files persist in LangGraph state
  agent_state = create_agent(
      model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
      tools=[],
      middleware=[
          StateClaudeTextEditorMiddleware(
              allowed_path_prefixes=["/project"],
          ),
      ],
  )

  # Filesystem-based: Files persist on disk
  agent_fs = create_agent(
      model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
      tools=[],
      middleware=[
          FilesystemClaudeTextEditorMiddleware(
              root_path="/workspace",
              allowed_prefixes=["/src"],
              max_file_size_mb=10,
          ),
      ],
  )
  ```
</Accordion>

## Memory

Provide Claude's memory tool (`memory_20250818`) for persistent agent memory across conversation turns. The memory middleware is useful for the following:

* Long-running agent conversations
* Maintaining context across interruptions
* Task progress tracking
* Persistent agent state management

<Info>
  Claude's memory tool uses a `/memories` directory and automatically injects a system prompt encouraging the agent to check and update memory.
</Info>

**API reference:** [`StateClaudeMemoryMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.StateClaudeMemoryMiddleware), [`FilesystemClaudeMemoryMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.FilesystemClaudeMemoryMiddleware)

```python theme={null}
from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import StateClaudeMemoryMiddleware
from langchain.agents import create_agent

# State-based memory
agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
    tools=[],
    middleware=[
        StateClaudeMemoryMiddleware(),
    ],
)
```

<Accordion title="Configuration options">
  **[`StateClaudeMemoryMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.StateClaudeMemoryMiddleware) (state-based)**

  <ParamField body="allowed_path_prefixes" type="Sequence[str] | None">
    Optional list of allowed path prefixes. Defaults to `["/memories"]`.
  </ParamField>

  <ParamField body="system_prompt" type="str">
    System prompt to inject. Defaults to Anthropic's recommended memory prompt that encourages the agent to check and update memory.
  </ParamField>

  **[`FilesystemClaudeMemoryMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.FilesystemClaudeMemoryMiddleware) (filesystem-based)**

  <ParamField body="root_path" type="str" required>
    Root directory for file operations
  </ParamField>

  <ParamField body="allowed_prefixes" type="list[str] | None">
    Optional list of allowed virtual path prefixes. Defaults to `["/memories"]`.
  </ParamField>

  <ParamField body="max_file_size_mb" type="int" default="10">
    Maximum file size in MB
  </ParamField>

  <ParamField body="system_prompt" type="str">
    System prompt to inject
  </ParamField>
</Accordion>

<Accordion title="Full example">
  ```python theme={null}
  from langchain_anthropic import ChatAnthropic
  from langchain_anthropic.middleware import (
      StateClaudeMemoryMiddleware,
      FilesystemClaudeMemoryMiddleware,
  )
  from langchain.agents import create_agent


  # State-based: Memory persists in LangGraph state
  agent_state = create_agent(
      model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
      tools=[],
      middleware=[
          StateClaudeMemoryMiddleware(),
      ],
  )

  # Filesystem-based: Memory persists on disk
  agent_fs = create_agent(
      model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
      tools=[],
      middleware=[
          FilesystemClaudeMemoryMiddleware(
              root_path="/workspace",
          ),
      ],
  )

  # The agent will automatically:
  # 1. Check /memories directory at start
  # 2. Record progress and thoughts during execution
  # 3. Update memory files as work progresses
  ```
</Accordion>

## File search

Provide Glob and Grep search tools for files stored in LangGraph state. File search middleware is useful for the following:

* Searching through state-based virtual file systems
* Works with text editor and memory tools
* Finding files by patterns
* Content search with regex

**API reference:** [`StateFileSearchMiddleware`](https://reference.langchain.com/python/langchain/middleware/#langchain.agents.middleware.StateFileSearchMiddleware)

```python theme={null}
from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import (
    StateClaudeTextEditorMiddleware,
    StateFileSearchMiddleware,
)
from langchain.agents import create_agent

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
    tools=[],
    middleware=[
        StateClaudeTextEditorMiddleware(),
        StateFileSearchMiddleware(),  # Search text editor files
    ],
)
```

<Accordion title="Configuration options">
  <ParamField body="state_key" type="str" default="text_editor_files">
    State key containing files to search. Use `"text_editor_files"` for text editor files or `"memory_files"` for memory files.
  </ParamField>
</Accordion>

<Accordion title="Full example">
  The middleware adds Glob and Grep search tools that work with state-based files.

  ```python theme={null}
  from langchain_anthropic import ChatAnthropic
  from langchain_anthropic.middleware import (
      StateClaudeTextEditorMiddleware,
      StateClaudeMemoryMiddleware,
      StateFileSearchMiddleware,
  )
  from langchain.agents import create_agent


  # Search text editor files
  agent = create_agent(
      model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
      tools=[],
      middleware=[
          StateClaudeTextEditorMiddleware(),
          StateFileSearchMiddleware(state_key="text_editor_files"),
      ],
  )

  # Search memory files
  agent_memory = create_agent(
      model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
      tools=[],
      middleware=[
          StateClaudeMemoryMiddleware(),
          StateFileSearchMiddleware(state_key="memory_files"),
      ],
  )
  ```
</Accordion>

***

<Callout icon="pen-to-square" iconType="regular">
  [Edit the source of this page on GitHub.](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/middleware/anthropic.mdx)
</Callout>

<Tip icon="terminal" iconType="regular">
  [Connect these docs programmatically](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
</Tip>