Anthropic 中间件集成

使用 LangChain Python 与 Anthropic 中间件集成。

专为 Anthropic 的 Claude 模型设计的中间件。了解更多关于 中间件。

中间件	描述
提示词缓存	通过缓存重复的提示词前缀来降低成本
Bash 工具	使用本地命令执行执行 Claude 的原生 bash 工具
文本编辑器	为文件编辑提供 Claude 的文本编辑器工具
记忆	为持久化代理记忆提供 Claude 的记忆工具
文件搜索	用于基于状态的文件系统的搜索工具

中间件与工具

langchain-anthropic 提供了两种使用 Claude 原生工具的方式：

• 中间件（本页面）：生产就绪的实现，内置执行、状态管理和安全策略
• 工具（通过 bind_tools）：低级构建块，您需提供自己的执行逻辑

何时使用哪一个

用例	推荐	原因
带有 bash 的生产代理	中间件	持久会话、Docker 隔离、输出脱敏
基于状态的文件编辑	中间件	内置 LangGraph 状态持久化
文件系统文件编辑	中间件	写入磁盘并验证路径
自定义执行逻辑	工具	完全控制执行
快速原型	工具	更简单，自带回调
非代理用途与 bind_tools	工具	中间件需要 create_agent

功能对比

功能	中间件	工具
与 create_agent 配合工作	✅	✅
与 bind_tools 配合工作	❌	✅
内置状态管理	✅	❌
自定义 execute 回调	❌	✅

示例：中间件与工具对比

使用中间件（开箱即用解决方案）：

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import ClaudeBashToolMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import DockerExecutionPolicy

# 生产就绪，包含 Docker 隔离、会话管理等
agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    middleware=[
        ClaudeBashToolMiddleware(
            workspace_root="/workspace",
            execution_policy=DockerExecutionPolicy(image="python:3.11"),
            startup_commands=["pip install pandas"],
        ),
    ],
)

使用工具（自带执行）：

import subprocess

from anthropic.types.beta import BetaToolBash20250124Param
from langchain_anthropic import ChatAnthropic
from langchain.agents import create_agent
from langchain.tools import tool

tool_spec = BetaToolBash20250124Param(
    name="bash",
    type="bash_20250124",
    strict=True,
)

@tool(extras={"provider_tool_definition": tool_spec})
def bash(*, command: str, restart: bool = False, **kw):
    """Execute a bash command."""
    if restart:
        return "Bash session restarted"
    try:
        result = subprocess.run(
            command,
            shell=True,
            capture_output=True,
            text=True,
            timeout=30,
        )
        return result.stdout + result.stderr
    except Exception as e:
        return f"Error: {e}"


agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[bash],
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "List files in this directory"}]}
)
print(result["messages"][-1].content)

---

提示词缓存

通过在 Anthropic 服务器上缓存静态或重复的提示词内容（如系统提示词、工具定义和对话历史）来降低成本和延迟。此中间件实现了一种对话缓存策略，在最新消息之后放置缓存断点，允许将整个对话历史（包括最新的用户消息）缓存并在后续 API 调用中重用。

提示词缓存适用于以下场景：

• 具有长且静态系统提示词的应用程序，这些提示词在请求之间不会更改
• 拥有许多跨调用保持不变的 tool definitions 的代理
• 早期消息历史在多轮对话中被重用的对话
• 降低 API 成本和延迟至关重要的批量部署

了解更多关于 Anthropic 提示词缓存 策略和限制。

API 参考： AnthropicPromptCachingMiddleware

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-6"),
    system_prompt="<Your long system prompt here>",
    middleware=[AnthropicPromptCachingMiddleware(ttl="5m")],
)

配置选项

type · string · default: "ephemeral"

缓存类型。目前仅支持 'ephemeral'。

ttl · string · default: "5m"

缓存内容的生存时间。有效值：'5m' 或 '1h'

min_messages_to_cache · number · default: "0"

开始缓存之前的最小消息数

unsupported_model_behavior · string · default: "warn"

使用非 Anthropic 模型时的行为。选项：'ignore'、'warn' 或 'raise'

完整示例

该中间件会缓存每个请求中直到并包括最新消息的内容。在 TTL 窗口内（5 分钟或 1 小时）的后续请求中，之前看到的内容将从缓存中检索而不是重新处理，从而显著降低成本和延迟。

工作原理：

1. 第一次请求：系统提示词、工具和用户消息 “Hi, my name is Bob” 被发送到 API 并缓存
2. 第二次请求：缓存的内容（系统提示词、工具和第一条消息）从缓存中检索。只需要处理新消息 “What’s my name?”，加上第一次请求的模型响应
3. 此模式在每一轮继续，每个请求都重用缓存的对话历史

提示词缓存通过缓存 token 来降低 API 成本，但不提供对话记忆。要在跨调用的过程中持久化对话历史，请使用 checkpointer，例如 MemorySaver。

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import AnthropicPromptCachingMiddleware
from langchain.agents import create_agent
from langchain.messages import HumanMessage
from langchain_core.runnables import RunnableConfig
from langgraph.checkpoint.memory import MemorySaver


LONG_PROMPT = """
Please be a helpful assistant.

<Lots more context ...>
"""

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    system_prompt=LONG_PROMPT,
    middleware=[AnthropicPromptCachingMiddleware(ttl="5m")],
    checkpointer=MemorySaver(),  # 持久化对话历史
)

# 使用 thread_id 来维持跨调用的对话状态
config: RunnableConfig = {"configurable": {"thread_id": "user-123"}}

# 第一次调用：创建包含系统提示词、工具和 "Hi, my name is Bob" 的缓存
agent.invoke({"messages": [HumanMessage("Hi, my name is Bob")]}, config=config)

# 第二次调用：重用缓存的系统提示词、工具和之前的消息
# checkpointer 维护对话历史，因此代理记得 "Bob"
result = agent.invoke({"messages": [HumanMessage("What's my name?")]}, config=config)
print(result["messages"][-1].content)

你的名字是 Bob！你在我们对话开始时自我介绍时告诉过我的。

Bash 工具

使用本地命令执行执行 Claude 的原生 bash_20250124 工具。

Bash 工具中间件适用于以下场景：

• 使用带有本地执行的 Claude 内置 bash 工具
• 利用 Claude 优化的 bash 工具接口
• 需要持久 shell 会话的代理与 Anthropic 模型配合使用

此中间件包装了 ShellToolMiddleware 并将其作为 Claude 的原生 bash 工具公开。

API 参考： ClaudeBashToolMiddleware

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-6"),
    tools=[],
    middleware=[
        ClaudeBashToolMiddleware(
            workspace_root="/workspace",
        ),
    ],
)

配置选项

ClaudeBashToolMiddleware 接受来自 ShellToolMiddleware 的所有参数，包括：

workspace_root · str | Path | None

Shell 会话的基础目录

startup_commands · tuple[str, ...] | list[str] | str | None

会话启动时运行的命令

execution_policy · BaseExecutionPolicy | None

执行策略（HostExecutionPolicy、DockerExecutionPolicy 或 CodexSandboxExecutionPolicy）

redaction_rules · tuple[RedactionRule, ...] | list[RedactionRule] | None

清理命令输出的规则

有关完整配置详情，请参阅 Shell 工具。

完整示例

import tempfile

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import ClaudeBashToolMiddleware
from langchain.agents import create_agent
from langchain.agents.middleware import DockerExecutionPolicy

# 为此演示创建一个临时工作区目录。
# 在生产环境中，请使用持久化目录路径。
workspace = tempfile.mkdtemp(prefix="agent-workspace-")

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[
        ClaudeBashToolMiddleware(
            workspace_root=workspace,
            startup_commands=["echo 'Session initialized'"],
            execution_policy=DockerExecutionPolicy(
                image="python:3.11-slim",
            ),
        ),
    ],
)

# Claude 现在可以使用其原生的 bash 工具
result = agent.invoke(
    {"messages": [{"role": "user", "content": "What version of Python is installed?"}]}
)
print(result["messages"][-1].content)

Python 3.11.14 is installed.

文本编辑器

为文件创建和编辑提供 Claude 的文本编辑器工具 (text_editor_20250728)。

文本编辑器中间件适用于以下场景：

• 基于文件的代理工作流
• 代码编辑和重构任务
• 多文件项目工作
• 需要持久化文件存储的代理

提供两种变体：基于状态的（LangGraph 状态中的文件）和基于文件系统的（磁盘上的文件）。

API 参考：

• StateClaudeTextEditorMiddleware
• FilesystemClaudeTextEditorMiddleware

State-based text editor

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import StateClaudeTextEditorMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[StateClaudeTextEditorMiddleware()],
)

Filesystem-based text editor

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import FilesystemClaudeTextEditorMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[
        FilesystemClaudeTextEditorMiddleware(
            root_path="/workspace",
        ),
    ],
)

Claude 的文本编辑器工具支持以下命令：

• view - 查看文件内容或列出目录
• create - 创建新文件
• str_replace - 替换文件中的字符串
• insert - 在行号处插入文本
• delete - 删除文件
• rename - 重命名/移动文件

配置选项

StateClaudeTextEditorMiddleware（基于状态）

allowed_path_prefixes · Sequence[str] | None

可选的允许路径前缀列表。如果指定，则只允许以这些前缀开头的路径。

FilesystemClaudeTextEditorMiddleware（基于文件系统）

root_path · str · required

文件操作的基础目录

allowed_prefixes · list[str] | None

可选的允许虚拟路径前缀列表（默认：["/"]）

max_file_size_mb · int · default: "10"

最大文件大小（MB）

完整示例：基于状态的文本编辑器

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import StateClaudeTextEditorMiddleware
from langchain.agents import create_agent
from langchain_core.runnables import RunnableConfig
from langgraph.checkpoint.memory import MemorySaver


agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[
        StateClaudeTextEditorMiddleware(
            allowed_path_prefixes=["/project"],
        ),
    ],
    checkpointer=MemorySaver(),
)

# 使用 thread_id 来持久化跨调用的状态
config: RunnableConfig = {"configurable": {"thread_id": "my-session"}}

# Claude 现在可以创建和编辑文件（存储在 LangGraph 状态中）
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Create a file at /project/hello.py with a simple hello world program"}]},
    config=config,
)
print(result["messages"][-1].content)

I've created a simple "Hello, World!" program at `/project/hello.py`. The program uses Python's `print()` function to display "Hello, World!" to the console when executed.

完整示例：基于文件系统的文本编辑器

import tempfile

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import FilesystemClaudeTextEditorMiddleware
from langchain.agents import create_agent


# 为此演示创建一个临时工作区目录。
# 在生产环境中，请使用持久化目录路径。
workspace = tempfile.mkdtemp(prefix="editor-workspace-")

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[
        FilesystemClaudeTextEditorMiddleware(
            root_path=workspace,
            allowed_prefixes=["/src"],
            max_file_size_mb=10,
        ),
    ],
)

# Claude 现在可以创建和编辑文件（存储在磁盘上）
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Create a file at /src/hello.py with a simple hello world program"}]}
)
print(result["messages"][-1].content)

I've created a simple "Hello, World!" program at `/src/hello.py`. The program uses Python's `print()` function to display "Hello, World!" to the console when executed.

记忆

为跨对话回合的持久化代理记忆提供 Claude 的记忆工具 (memory_20250818)。

记忆中间件适用于以下场景：

• 长期运行的代理对话
• 在中断期间保持上下文
• 任务进度跟踪
• 持久化代理状态管理

Claude 的记忆工具使用 /memories 目录，并自动注入一个鼓励代理检查和更新记忆的系统提示词。

API 参考： StateClaudeMemoryMiddleware，FilesystemClaudeMemoryMiddleware

State-based memory

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import StateClaudeMemoryMiddleware
from langchain.agents import create_agent

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[StateClaudeMemoryMiddleware()],
)

Filesystem-based memory

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import FilesystemClaudeMemoryMiddleware
from langchain.agents import create_agent

agent_fs = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[
        FilesystemClaudeMemoryMiddleware(
            root_path="/workspace",
        ),
    ],
)

配置选项

StateClaudeMemoryMiddleware（基于状态）

allowed_path_prefixes · Sequence[str] | None

可选的允许路径前缀列表。默认为 ["/memories"]。

system_prompt · str

要注入的系统提示词。默认为 Anthropic 推荐的记忆提示词，鼓励代理检查和更新记忆。

FilesystemClaudeMemoryMiddleware（基于文件系统）

root_path · str · required

文件操作的基础目录

allowed_prefixes · list[str] | None

可选的允许虚拟路径前缀列表。默认为 ["/memories"]。

max_file_size_mb · int · default: "10"

最大文件大小（MB）

system_prompt · str

要注入的系统提示词

完整示例：基于状态的记忆

代理将自动：

1. 在开始时检查 /memories 目录
2. 在执行期间记录进度和想法
3. 随着工作进展更新记忆文件

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import StateClaudeMemoryMiddleware
from langchain.agents import create_agent
from langchain_core.runnables import RunnableConfig
from langgraph.checkpoint.memory import MemorySaver


agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[StateClaudeMemoryMiddleware()],
    checkpointer=MemorySaver(),
)

# 使用 thread_id 来持久化跨调用的状态
config: RunnableConfig = {"configurable": {"thread_id": "my-session"}}

# Claude 现在可以使用记忆来跟踪进度（存储在 LangGraph 状态中）
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Remember that my favorite color is blue, then confirm what you stored."}]},
    config=config,
)
print(result["messages"][-1].content)

Perfect! I've stored your favorite color as **blue** in my memory system. The information is saved in my user preferences file where I can access it in future conversations.

完整示例：基于文件系统的记忆

代理将自动：

1. 在开始时检查 /memories 目录
2. 在执行期间记录进度和想法
3. 随着工作进展更新记忆文件

import tempfile

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import FilesystemClaudeMemoryMiddleware
from langchain.agents import create_agent


# 为此演示创建一个临时工作区目录。
# 在生产环境中，请使用持久化目录路径。
workspace = tempfile.mkdtemp(prefix="memory-workspace-")

agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[
        FilesystemClaudeMemoryMiddleware(
            root_path=workspace,
        ),
    ],
)

# Claude 现在可以使用记忆来跟踪进度（存储在磁盘上）
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Remember that my favorite color is blue, then confirm what you stored."}]}
)
print(result["messages"][-1].content)

Perfect! I've stored your favorite color as **blue** in my memory system. The information is saved in my user preferences file where I can access it in future conversations.

文件搜索

为存储在 LangGraph 状态中的文件提供 Glob 和 Grep 搜索工具。文件搜索中间件适用于以下场景：

• 搜索基于状态的虚拟文件系统
• 与文本编辑器和记忆工具配合使用
• 按模式查找文件
• 使用正则表达式进行内容搜索

API 参考： StateFileSearchMiddleware

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-6"),
    tools=[],
    middleware=[
        StateClaudeTextEditorMiddleware(),
        StateFileSearchMiddleware(),  # 搜索文本编辑器文件
    ],
)

配置选项

state_key · str · default: "text_editor_files"

包含要搜索文件的键。对于文本编辑器文件使用 "text_editor_files"，对于记忆文件使用 "memory_files"。

完整示例：搜索文本编辑器文件

中间件添加了可与基于状态的文件配合使用的 Glob 和 Grep 搜索工具。

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import (
    StateClaudeTextEditorMiddleware,
    StateFileSearchMiddleware,
)
from langchain.agents import create_agent
from langchain.messages import HumanMessage
from langchain_core.runnables import RunnableConfig
from langgraph.checkpoint.memory import MemorySaver


agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[
        StateClaudeTextEditorMiddleware(),
        StateFileSearchMiddleware(state_key="text_editor_files"),
    ],
    checkpointer=MemorySaver(),
)

# 使用 thread_id 来持久化跨调用的状态
config: RunnableConfig = {"configurable": {"thread_id": "my-session"}}

# 第一次调用：使用文本编辑器工具创建一些文件
result = agent.invoke(
    {"messages": [HumanMessage("Create a Python project with main.py, utils/helpers.py, and tests/test_main.py")]},
    config=config,
)

# 代理创建文件，这些文件存储在状态中
print("Files created:", list(result["text_editor_files"].keys()))

# 第二次调用：搜索我们刚刚创建的文件
# 状态通过 checkpointer 自动持久化
result = agent.invoke(
    {"messages": [HumanMessage("Find all Python files in the project")]},
    config=config,
)
print(result["messages"][-1].content)

Files created: ['/project/main.py', '/project/utils/helpers.py', '/project/utils/__init__.py', '/project/tests/test_main.py', '/project/tests/__init__.py', '/project/README.md']

I found 5 Python files in the project:

1. `/project/main.py` - Main application file
2. `/project/utils/__init__.py` - Utils package initialization
3. `/project/utils/helpers.py` - Helper utilities
4. `/project/tests/__init__.py` - Tests package initialization
5. `/project/tests/test_main.py` - Main test file

Would you like me to view the contents of any of these files?

完整示例：搜索记忆文件

from langchain_anthropic import ChatAnthropic
from langchain_anthropic.middleware import (
    StateClaudeMemoryMiddleware,
    StateFileSearchMiddleware,
)
from langchain.agents import create_agent
from langchain.messages import HumanMessage
from langchain_core.runnables import RunnableConfig
from langgraph.checkpoint.memory import MemorySaver


agent = create_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    tools=[],
    middleware=[
        StateClaudeMemoryMiddleware(),
        StateFileSearchMiddleware(state_key="memory_files"),
    ],
    checkpointer=MemorySaver(),
)

# 使用 thread_id 来持久化跨调用的状态
config: RunnableConfig = {"configurable": {"thread_id": "my-session"}}

# 第一次调用：记录一些记忆
result = agent.invoke(
    {"messages": [HumanMessage("Remember that the project deadline is March 15th and code review deadline is March 10th")]},
    config=config,
)

# 代理创建记忆文件，这些文件存储在状态中
print("Memory files created:", list(result["memory_files"].keys()))

# 第二次调用：搜索我们刚刚记录的记忆
# 状态通过 checkpointer 自动持久化
result = agent.invoke(
    {"messages": [HumanMessage("Search my memories for project deadlines")]},
    config=config,
)
print(result["messages"][-1].content)

Memory files created: ['/memories/project_info.md']

I found your project deadlines in my memory! Here's what I have recorded:

## Important Deadlines
- **Code Review Deadline:** March 10th
- **Project Deadline:** March 15th

## Notes
- Code review must be completed 5 days before final project deadline
- Need to ensure all code is ready for review by March 10th

Is there anything specific about these deadlines you'd like to know or update?

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.