为 Managed Deep Agents 添加自定义中间件

为托管 deep agent 添加内置或自定义中间件。

中间件会在模型调用、工具调用和 agent 生命周期周围增加行为。与自定义工具一样，MDA 不会自动发现中间件。你需要导入它，并将其传给 agent 定义。

NOTE

Managed Deep Agents 处于公开 beta 阶段，仅在 US 区域的 LangSmith Cloud 上可用。

将自定义中间件放在 middleware/ 下，导入到 agent 入口，并传给 agent 定义：

my-agent/
  agent.py
  middleware/
    audit.py

有关完整项目布局，请参阅项目结构。

托管运行时仍然掌管 backend、store、checkpointer、memory、skills 和系统提示词。中间件应聚焦于模型调用、工具调用和生命周期钩子周围的 agent 行为。

添加中间件

你可以用中间件来脱敏 PII、限制调用次数、重试失败、在模型之间回退、动态选择模型，或记录和检查工具调用。

Use prebuilt middleware

你可以直接在 agent 定义中使用 LangChain 预置中间件：

from langchain.agents.middleware import ModelCallLimitMiddleware, PIIMiddleware
from managed_deepagents import define_deep_agent

agent = define_deep_agent(
    name="support-agent",
    model="openai:gpt-5.5",
    middleware=[
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        ModelCallLimitMiddleware(run_limit=50),
    ],
)

Define custom middleware (Optional)

如需更进阶的方案，可在本地模块中定义自定义中间件。

NOTE

中间件是 LangChain 的共享原语。Managed Deep Agents 始终使用 ainvoke 和 astream 调用 agent，因此自定义中间件必须使用异步钩子。当你用 invoke 或 stream 调用 Deep Agents 时，同步钩子仍然可用。

from collections.abc import Awaitable, Callable

from langchain.agents.middleware import wrap_tool_call
from langchain.messages import ToolMessage
from langchain.tools.tool_node import ToolCallRequest
from langgraph.types import Command

@wrap_tool_call
async def log_tool_calls(
    request: ToolCallRequest,
    handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
    print(f"Calling tool: {request.tool_call['name']}")
    result = await handler(request)
    print(f"Finished tool: {request.tool_call['name']}")
    return result

将中间件导入项目根目录的 agent 入口，并放入 middleware 列表：

from managed_deepagents import define_deep_agent

from middleware.audit import log_tool_calls

agent = define_deep_agent(
    name="support-agent",
    model="openai:gpt-5.5",
    middleware=[log_tool_calls],
)

中间件的导入方式应与普通本地 Python 项目一致。

使用运行时上下文

中间件可以通过常规的 LangChain 运行时 API 读取每次 run 的上下文。上下文适用于用户 ID、组织 ID、功能开关、请求元数据，或默认不应进入模型提示词的凭据。

示例请参见自定义中间件。

要在中间件钩子中读写线程沙箱里的文件，请使用 runtime.backend。参见从代码读写沙箱文件。

部署

mda dev 和 mda deploy 会把项目文件复制进编译产物，包括 middleware/ 下的模块。中间件不会同步到 Context Hub；它随 agent 代码一起发布。

何时使用中间件

概念	类型	如何到达 agent
Middleware	应用代码	在 agent 定义中导入并传入
自定义工具	应用代码	在 agent 定义中导入并传入
Instructions	托管上下文	始终启用的系统提示词

更多信息请参阅项目结构。

---