代理中间件
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Agentic Middleware
Middleware is how you compose cross-cutting agent behavior in LangChain v1+. It plugs into `create_agent(...)` (and is the underlying implementation of DeepAgents). **For any production agent, the question is "which middlewares" — not "do I need middleware".**
## The model
```python
from langchain.agents import create_agent
from langchain.agents.middleware import (
SummarizationMiddleware,
ModelRetryMiddleware,
ModelFallbackMiddleware,
ModelCallLimitMiddleware,
ToolRetryMiddleware,
PIIMiddleware,
)
agent = create_agent(
model="claude-sonnet-4-6",
tools=[...],
middleware=[
ModelRetryMiddleware(max_retries=3, backoff_factor=2.0, initial_delay=1.0),
ModelFallbackMiddleware("openai:gpt-4o-mini"),
ModelCallLimitMiddleware(run_limit=50),
ToolRetryMiddleware(max_retries=3, backoff_factor=2.0),
SummarizationMiddleware(model="claude-haiku-4-5", trigger=("tokens", 4000), keep=("messages", 20)),
PIIMiddleware("email", strategy="redact", apply_to_input=True),
],
)
```
`create_agent` returns a compiled LangGraph. All `Runnable` semantics apply: `.invoke`, `.ainvoke`, `.stream`, `.astream`, `langgraph dev`, `langgraph build`, etc.
## Lifecycle hooks (for custom middleware)
Every middleware can override one or more of these:
| Hook | Fires | Return |
|---|---|---|
| `before_agent(state, runtime)` | Once, before the loop starts | dict to merge into state, or None |
| `before_model(state, runtime)` | Before each model call | dict to merge into state, or None |
| `wrap_model_call(request, handler)` | Wraps the model call | call `handler(request)` → `ModelResponse`; return it (possibly modified) |
| `after_model(state, runtime)` | After each model response | dict to merge into state, or None |
| `wrap_tool_call(request, handler)` | Wraps each tool call | call `handler(request)` → `ToolMessage \| Command`; return it (possibly modified) |
| `after_agent(state, runtime)` | Once, after the loop ends | dict to merge into state, or None |
Node-style hooks (`before_*` / `after_*`) run sequentially. Wrap-style hooks compose like Python decorators — **first middleware in the list is the outermost wrapper**.
## Built-in middlewares (provider-agnostic)
Import from `langchain.agents.middleware`:
| Middleware | Purpose | Constructor |
|---|---|---|
| `SummarizationMiddleware` | Auto-summarize long conversations to stay under token limits | `(model, trigger=("tokens", N), keep=("messages", N))` |
| `HumanInTheLoopMiddleware` | Pause for human approve/edit/reject on sensitive tool calls | `(interrupt_on={"tool_name": {"allowed_decisions": [...]}})` — **requires a checkpointer** |
| `ModelCallLimitMiddleware` | Cap model calls per run / per thread (cost containment, infinite-loop guard) | `(thread_limit, run_limit, exit_behavior="end")` |
| `ToolCallLimitMiddleware` | Cap tool calls globally or per-tool | `(thread_limit, run_limit)` or `(tool_name, thread_limit, run_limit)` |
| `ModelRetryMiddleware` | Retry transient model failures with exponential backoff | `(max_retries, backoff_factor, initial_delay)` |
| `ToolRetryMiddleware` | Retry transient tool failures with exponential backoff | same args |
| `ModelFallbackMiddleware` | Fall back to alternative models on primary failure | `("model-1", "model-2", ...)` |
| `LLMToolSelectorMiddleware` | Use a small LLM to pick which tools to expose to the main model | `(model, max_tools, always_include=[...])` |
| `PIIMiddleware` | Detect & redact / mask / block PII | `("email"\|"credit_card"\|..., strategy="redact"\|"mask"\|"block", apply_to_input=True)` |
| `ContextEditingMiddleware` | Drop old tool outputs from context to free tokens | `(edits=[ClearToolUsesEdit(trigger, keep)])` |
| `TodoListMiddleware` | Adds the `write_todos` planning tool to the agent | `()` |
| `LLMToolEmulator` | Replace tool execution with LLM-generated outputs (testing) | `()` — never use in production |
| `ShellToolMiddleware` | Persistent shell session as a tool, with execution policy | `(workspace_root, execution_policy)` |
| `FilesystemFileSearchMiddleware` | Glob + Grep tools over a filesystem | `(root_path, use_ripgrep=True)` |
DeepAgents-specific (import from `deepagents.middleware`):
| Middleware | Purpose |
|---|---|
| `FilesystemMiddleware` | Virtual or backed filesystem for the agent (read/write/edit/ls/glob/grep) |
| `SubAgentMiddleware` | Adds the `task` tool with named sub-agents |
`create_deep_agent(...)` is a thin wrapper over `create_agent(...)` that pre-installs `FilesystemMiddleware` + `SubAgentMiddleware` + `TodoListMiddleware`. You can compose additional middlewares on top.
## Production middleware stack (start here)
For any production agent, this is the default stack to copy and tune:
```python
middleware=[
# Cost containment (set BEFORE retries — limits the multiplier)
ModelCallLimitMiddleware(run_limit=50),
ToolCallLimitMiddleware(run_limit=200),
# Resilience to transient failures
ModelRetryMiddleware(max_retries=3, backoff_factor=2.0, initial_delay=1.0),
ToolRetryMiddleware(max_retries=3, backoff_factor=2.0, initial_delay=1.0),
# Provider-level resilience
ModelFallbackMiddleware("openai:gpt-4o-mini"),
# Long-conversation hygiene
SummarizationMiddleware(model="claude-haiku-4-5", trigger=("tokens", 8000), keep=("messages", 20)),
# Privacy (only if user input may contain PII)
PIIMiddleware("email", strategy="redact", apply_to_input=True),
PIIMiddleware("credit_card", strategy="mask", apply_to_input=True),
]
```
Add `HumanInTheLoopMiddleware` for any tool that touches money, sends external messages, or makes irreversible changes. **Requires a checkpointer** (`InMemorySaver` for dev, `PostgresSaver` for production — see the deploy skill).
## Custom middleware
Inherit from `AgentMiddleware`:
```python
from typing import Any, Callable
from langchain.agents.middleware import (
AgentMiddleware, AgentState, ModelRequest, ModelResponse,
)
from langchain.tools.tool_node import ToolCallRequest
from langchain.messages import ToolMessage
from langgraph.types import Command
class TokenBudgetMiddleware(AgentMiddleware):
"""Hard-cap total tokens across the run. Halts the agent when exceeded."""
def __init__(self, budget: int) -> None:
self.budget = budget
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelResponse:
used = request.state.get("tokens_used", 0)
if used >= self.budget:
# short-circuit: return a synthetic "stop" response without calling the model
return ModelResponse(
messages=[{"role": "assistant", "content": "Token budget exceeded."}],
command=Command(goto="__end__"),
)
response = handler(request)
# ... extract token count from response.usage and add to state
return response
```
If you need extra fields in state, declare them on a subclass of `AgentState` and set `state_schema = MyState` on the middleware class.
## Hard rules
- **Order matters.** Limits before retries (so retries don't burn through your budget). Privacy redaction before logging. Summarization should run *before* the model call, not after.
- **HumanInTheLoopMiddleware needs a checkpointer.** Without one, interrupts have nothing to resume from.
- **`LLMToolEmulator` is a testing-only middleware.** Never ship it.
- **Retries cost money.** A `max_retries=3` with `backoff_factor=2` means up to 4 calls per failure. Set `ModelCallLimitMiddleware` BEFORE retries to cap the worst-case cost.
- **Don't roll your own retry/fallback/limit.** The built-ins handle the edge cases (jitter, retryable error classification, streaming-aware wrapping). Custom middleware is for app-specific concerns.
## Skills to load alongside this one
- `langchain-agents-deploy` — productionisation: durable execution, checkpointers, deployment.
- `langchain-agents-observability` — tracing what middleware actually does at runtime.
- `langchain-agents-langgraph-code` — when to drop down to raw `StateGraph` (rare, but real cases exist).
---
> Source: [cwijayasundara/agent_cli_langchain](https://github.com/cwijayasundara/agent_cli_langchain) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
型号
生命周期挂钩(用于自定义中间件)
内置中间件(与提供商无关)
生产中间件堆栈(从这里开始)
定制中间件
文件/命令 -> create_agent(...) · create_agent · Runnable · .invoke · .ainvoke · .stream · .astream · langgraph dev
内容校验值 -> 88e854f1b590
当前原文的自动摘译,尚未人工审校。
型号
create_agent返回编译后的 LangGraph。所有Runnable语义均适用:.invoke、.ainvoke、.stream、.astream、langgraph dev、langgraph build等。生命周期挂钩(用于自定义中间件)
每个中间件都可以覆盖其中的一个或多个: Hook · Fires · Return
before_agent(state, runtime)· 一次,在循环开始之前 · dict 合并到状态,或 Nonebefore_model(state, runtime)· 在每个模型调用之前 · dict 合并到状态,或 Nonewrap_model_call(request, handler)· 包装模型调用 · callhandler(request)→ModelResponse;返回它(可能已修改)内置中间件(与提供商无关)
从
langchain.agents.middleware导入:中间件 · 目的 · 构造函数SummarizationMiddleware· 自动总结长对话以保持在令牌限制之下 ·(model, trigger=("tokens", N), keep=("messages", N))HumanInTheLoopMiddleware· 暂停以供人工批准/编辑/拒绝敏感工具调用 ·(interrupt_on={"tool_name": {"allowed_decisions": [...]}})- 需要检查点生产中间件堆栈(从这里开始)
对于任何生产代理,这是要复制和调整的默认堆栈:为任何涉及金钱、发送外部消息或进行不可逆转更改的工具添加
HumanInTheLoopMiddleware。需要一个检查点(InMemorySaver用于开发,PostgresSaver用于生产 - 请参阅部署技能)。定制中间件
继承
AgentMiddleware:如果状态中需要额外的字段,请在AgentState的子类上声明它们,并在中间件类上设置state_schema = MyState。