fix(docs): update middleware guide to current AgentMiddleware API (#4968)

backend/CONTRIBUTING.md

@@ -276,28 +276,28 @@ tools:
 
 ```python
 # packages/harness/deerflow/agents/middlewares/my_middleware.py
-from langchain.agents.middleware import BaseMiddleware
-from langchain_core.runnables import RunnableConfig
+from langchain.agents import AgentState
+from langchain.agents.middleware import AgentMiddleware
+from langgraph.runtime import Runtime
 
-class MyMiddleware(BaseMiddleware):
+class MyMiddleware(AgentMiddleware[AgentState]):
     """Middleware description."""
 
-    def transform_state(self, state: dict, config: RunnableConfig) -> dict:
-        """Transform the state before agent execution."""
-        # Modify state as needed
-        return state
+    def before_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        """Runs before each model call. Return a dict of state updates, or None."""
+        return None
+
+    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        """Runs after each model call. Inspect or modify the result."""
+        return None
 ```
 
-2. Register in `packages/harness/deerflow/agents/lead_agent/agent.py`:
+2. Register via `custom_middlewares` when building the agent:
 
 ```python
-middlewares = [
-    ThreadDataMiddleware(),
-    SandboxMiddleware(),
-    MyMiddleware(),  # Add your middleware
-    TitleMiddleware(),
-    ClarificationMiddleware(),
-]
+middlewares = build_middlewares(
+    config, model_name, custom_middlewares=[MyMiddleware()], ...
+)
 ```
 
 ### Adding New API Endpoints

frontend/src/content/en/harness/customization.mdx

@@ -25,19 +25,21 @@ To add a custom middleware:
 2. Pass your middleware to the `custom_middlewares` parameter when building the agent.
 
 ```python
+from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
-from deerflow.agents.thread_state import ThreadState
+from langgraph.runtime import Runtime
 
-class AuditMiddleware(AgentMiddleware):
-    async def on_start(self, state: ThreadState, config):
-        # Runs before each model call
+
+class AuditMiddleware(AgentMiddleware[AgentState]):
+    def before_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        """Runs before each model call."""
         print(f"[audit] turn starts: {len(state.messages)} messages in context")
-        return state, config
+        return None
 
-    async def on_end(self, state: ThreadState, config):
-        # Runs after each model call
+    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        """Runs after each model call."""
         print(f"[audit] turn ends: last message type = {state.messages[-1].type}")
-        return state, config
+        return None
 ```
 
 Custom middlewares are injected into the chain immediately before `ClarificationMiddleware`, which always runs last.

frontend/src/content/en/harness/middlewares.mdx

@@ -235,15 +235,13 @@ The basic structure is:
 from langchain.agents.middleware import AgentMiddleware
 
 class MyMiddleware(AgentMiddleware):
-    async def on_start(self, state, config):
-        # Runs before the model call
-        # Modify state or config here
-        return state, config
+    def before_model(self, state, runtime) -> dict | None:
+        """Runs before each model call."""
+        return None
 
-    async def on_end(self, state, config):
-        # Runs after the model call
-        # Inspect or modify the result
-        return state, config
+    def after_model(self, state, runtime) -> dict | None:
+        """Runs after each model call."""
+        return None
 ```
 
 Custom middlewares are passed to `make_lead_agent` via the `custom_middlewares` parameter in `build_middlewares`. They are injected immediately before `ClarificationMiddleware` at the end of the chain.

frontend/src/content/zh/harness/customization.mdx

@@ -25,19 +25,21 @@ DeerFlow 的可插拔架构意味着系统的大多数部分都可以在不 fork
 2. 在构建 Agent 时通过 `custom_middlewares` 参数传入你的中间件。
 
 ```python
+from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
-from deerflow.agents.thread_state import ThreadState
+from langgraph.runtime import Runtime
 
-class AuditMiddleware(AgentMiddleware):
-    async def on_start(self, state: ThreadState, config):
-        # 在每次模型调用前运行
+
+class AuditMiddleware(AgentMiddleware[AgentState]):
+    def before_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        """在每次模型调用前运行。"""
         print(f"[审计] 轮次开始：上下文中有 {len(state.messages)} 条消息")
-        return state, config
+        return None
 
-    async def on_end(self, state: ThreadState, config):
-        # 在每次模型调用后运行
+    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        """在每次模型调用后运行。"""
         print(f"[审计] 轮次结束：最后一条消息类型 = {state.messages[-1].type}")
-        return state, config
+        return None
 ```
 
 自定义中间件在链末尾 `ClarificationMiddleware` 之前注入，后者始终最后运行。

frontend/src/content/zh/harness/middlewares.mdx

@@ -216,16 +216,19 @@ summarization:
 自定义中间件可以注入到链中用于专业用途。中间件必须实现 `langchain.agents.middleware` 中的 `AgentMiddleware` 接口：
 
 ```python
+from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
+from langgraph.runtime import Runtime
 
-class MyMiddleware(AgentMiddleware):
-    async def on_start(self, state, config):
-        # 在模型调用前运行
-        return state, config
 
-    async def on_end(self, state, config):
-        # 在模型调用后运行
-        return state, config
+class MyMiddleware(AgentMiddleware[AgentState]):
+    def before_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        """在模型调用前运行。"""
+        return None
+
+    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        """在模型调用后运行。"""
+        return None
 ```
 
 自定义中间件在链末尾 `ClarificationMiddleware` 之前注入。