LangChain 进阶 on 扎塔-Zata

LangGraph 实战：StateGraph、手写 ReAct 循环与 Map-Reduce 摘要

Tue, 08 Sep 2026 12:30:00 +0800

LangGraph 实战：StateGraph、手写 ReAct 循环与 Map-Reduce 摘要

LangChain 进入 1.x 之后，LangGraph 不再是"进阶选读"，而是整个框架的编排核心：官方一行式 create_agent 的底下就是一张 LangGraph 图，Agent 的决策、工具调用、记忆全在图上跑。看懂 LangGraph，基本等于看懂 Agent 本身。

这篇文章解决三件事。一是把 StateGraph、State、条件边这几个地基概念一次讲透；二是不用任何 Agent 封装，手写一遍 tool-call 循环——写完你会发现 Agent 没有魔法，它就是消息列表上转的一圈代码；三是用 LangGraph 把这个循环工程化成完整的 ReAct 天气助手，再补一个 Map-Reduce 长文本摘要图和记忆持久化。

文章由我 2025 年 5～6 月的三篇笔记（《Langchain-Graph实战教程》《LangChain-实战-Tools使用教程》《Langgraph使用教程》）整合而成。合并时修正了原笔记的几处真实 bug——条件边示例的构建顺序与路由映射错误、手动循环里对 tool_call["args"] 多加的一句 json.loads——过时 API 统一在文末版本注记里交代。全文示例模型走阿里云 DashScope 的 qwen 系（qwen-plus / qwen-max）OpenAI 兼容端点，只需要一个 DASHSCOPE_API_KEY 环境变量。

前五节是地基，任何版本都用得上。第六节是 2026 年的新增内容：LangGraph 1.1 / 1.2 给节点加上了超时、错误处理器和优雅停机，还给流式输出换了一套以内容块为中心的 API。这几样是"从能跑到敢上生产"之间的那段距离，值得单独看。

1. 基础三件套：StateGraph、State 与条件边

1.1 StateGraph：把应用建成一张状态机

StateGraph 把应用定义为状态机：节点（node）是执行单元，通常是普通 Python 函数；边（edge）决定流程如何在节点之间转换。构建一张图固定是四步：

定义 State——图运行时传递的数据结构
add_node 添加节点
连边：普通边写死流转，条件边动态路由，入口用 START
compile() 编译成可执行应用，之后用 invoke 跑

依赖安装一次说清：pip install langchain langgraph langchain_openai。

1.2 State 与 Annotated：覆盖还是追加

State 是一个 TypedDict，定义图的模式和状态更新方式。聊天场景下 State 通常只有一个键：messages。关键在 add_messages 这个 reducer 函数——它决定新消息是追加进列表，而不是覆盖列表：

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages

class State(TypedDict):
 # Messages 的类型是 "list"。`add_messages` 函数
 # 在注解中定义了如何更新这个状态键
 # （在这种情况下，它会将消息追加到列表中，而不是覆盖它们）
 messages: Annotated[list, add_messages]

Annotated 是 Python 类型提示系统的特殊类型，允许为类型附加元数据。在 LangGraph 里它承担两个职责：

类型定义：第一个参数 list 表示 messages 字段是列表
行为定义：第二个参数 add_messages 是 reducer 函数，定义这个键怎么更新——新消息到来时追加进现有列表，而不是整体替换

两种语义的区别直观感受一下：

# 不使用 Annotated（默认行为：覆盖）
state = {"messages": ["消息1"]}
state["messages"] = ["消息2"]
# 结果：["消息2"]

# 使用 Annotated + add_messages
state = {"messages": ["消息1"]}
# 新消息到来时，add_messages 将其追加到列表
# 结果：["消息1", "消息2"]

这种设计在对话场景特别有用：保持对话历史、消息按顺序累积、不会意外覆盖。反过来，没有 reducer 注解的字段就是"最后一次写入覆盖"的语义——第 4 节 Map-Reduce 的流水线正好要靠这个默认行为。

1.3 MessagesState：内置的消息状态

自己写 Annotated[list, add_messages] 是标准做法，LangGraph 也把它做成了内置状态类 MessagesState，位于 langgraph.graph 模块，专为对话场景设计。它内部维护一个 messages 键，等价于：

class MessagesState(TypedDict):
 messages: Annotated[list, add_messages]

它的特点：

与 LangChain 的消息类型（HumanMessage、AIMessage、SystemMessage、ToolMessage）直接兼容
节点返回 {"messages": [...]} 时自动追加进消息列表
可以通过继承扩展自定义字段

一个能跑通的最小示例：

import os
from langgraph.graph import MessagesState, StateGraph, START, END
from langchain_core.messages import HumanMessage
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
 model="qwen-plus",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
)

def chatbot_node(state: MessagesState):
 # 取出当前消息，调用 LLM；返回值会自动追加进 messages
 response = llm.invoke(state["messages"])
 return {"messages": [response]}

graph = StateGraph(MessagesState)
graph.add_node("chatbot", chatbot_node)
graph.add_edge(START, "chatbot")
graph.add_edge("chatbot", END)
app = graph.compile()

result = app.invoke({"messages": [HumanMessage(content="你好！今天能帮我什么？")]})
for message in result["messages"]:
 print(f"{message.__class__.__name__}: {message.content}")

运行后会打印两条消息：一条 HumanMessage，一条 LLM 追加的 AIMessage。

需要扩展状态时，继承加字段即可：

class CustomMessagesState(MessagesState):
 user_id: str
 session_id: int

graph = StateGraph(CustomMessagesState)

状态将包含 messages 列表以及 user_id 和 session_id，节点可读写这些字段。两个使用注意：消息必须符合 BaseMessage 或兼容格式，塞普通字符串会出问题；长对话历史要么确认模型的上下文窗口装得下，要么自己加截断策略。

1.4 条件边：让图自己决定下一步

普通边是写死的流转，条件边（add_conditional_edges）根据状态动态路由：条件函数的返回值经过映射字典决定下一个节点。这是 LangGraph 表达分支逻辑的方式，也是后面 ReAct 循环里"有 tool_calls 就去执行工具、没有就结束"的实现基础。

下面这个示例修正过原笔记的两处问题：一是 add_edge(START, "router") 写在了 add_node("router", ...) 之前——节点还没注册就连边，LangGraph 校验阶段直接报错；二是路由函数返回 "help_node" / "chatbot_node"，与图中实际节点名 "help" / "chatbot" 错位，而且同一个函数既被当节点又被当条件函数。修正思路：路由函数只作为条件函数，从 START 直接条件路由，返回值与节点名严格对齐。

from typing import Literal
from langgraph.graph import MessagesState, StateGraph, START, END
from langchain_core.messages import HumanMessage, AIMessage

def route_by_intent(state: MessagesState) -> Literal["help", "chatbot"]:
 last_message = state["messages"][-1].content.lower()
 if "帮助" in last_message:
 return "help"
 return "chatbot"

def help_node(state: MessagesState):
 return {"messages": [AIMessage(content="这里是帮助信息！")]}

def chatbot_node(state: MessagesState):
 return {"messages": [AIMessage(content="来聊聊吧！")]}

graph = StateGraph(MessagesState)
graph.add_node("help", help_node)
graph.add_node("chatbot", chatbot_node)

# 条件边：起点是 START，路由函数的返回值映射到目标节点
graph.add_conditional_edges(
 START,
 route_by_intent,
 {"help": "help", "chatbot": "chatbot"},
)
graph.add_edge("help", END)
graph.add_edge("chatbot", END)

app = graph.compile()
result = app.invoke({"messages": [HumanMessage(content="我需要帮助")]})
print(result["messages"][-1].content) # 输出：这里是帮助信息！

add_conditional_edges 收三个参数：起点节点（这里用特殊节点 START）、条件函数、返回值到目标节点的映射字典。条件边也可以从普通节点出发——第 3 节的 should_continue 就是从 agent 节点出发的。

2. 手写 tool-call 循环：Agent 到底在替你做什么

在让 LangGraph 接管之前，值得把这个循环亲手写一遍。create_agent、AgentExecutor、ToolNode 这些封装拆开看没有魔法，核心就是：在消息列表上跑一圈循环。整个流程四步：

把用户消息和工具定义一起发给 LLM
检查响应里有没有 tool_calls
有：执行对应函数，结果包成 ToolMessage 回填进消息列表
带着完整消息再次调用 LLM，它基于工具结果生成最终回复

先定义模型和工具（沿用原笔记的三个 mock 工具）：

import os
from typing import List, Dict, Any, Optional
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage, ToolMessage

model = ChatOpenAI(
 model="qwen-plus",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
)

@tool
def get_weather(location: str, unit: str = "celsius") -> str:
 """获取指定位置的当前天气。"""
 return f"{location}当前天气晴朗，温度25{unit}"

@tool
def create_user(name: str, email: str, age: Optional[int] = None) -> Dict[str, Any]:
 """在系统中创建新用户。"""
 user = {"id": hash(email) % 10000, "name": name, "email": email}
 if age:
 user["age"] = age
 return user

@tool
def search_database(query: str) -> List[Dict[str, Any]]:
 """搜索数据库获取信息。"""
 if "产品A" in query:
 return [{"id": 1, "name": "产品A", "price": 99.99}]
 return []

tools = [get_weather, create_user, search_database]

# bind_tools：把工具定义绑定到 LLM，LLM 就"知道"这些工具的存在
llm_with_tools = model.bind_tools(tools)

# 工具名 -> Tool 对象，供手动执行时查找
available_tools = {t.name: t for t in tools}

@tool 装饰器把普通 Python 函数变成 LangChain 工具：函数签名和 docstring 会被转成 LLM 可读的工具描述——LLM 何时调用、怎么调用全靠 docstring。bind_tools(tools) 是关键一步：绑定之后，LLM 在认为合适时就会在响应里返回"工具调用请求"，而不是纯文本。

接下来是循环本身，不用任何 Agent 框架：

# 步骤 1：初始消息列表
messages = [
 HumanMessage(content="创建一个名为李四的用户，邮箱为lisi@example.com，年龄28岁。然后告诉我北京的天气。"),
]

# 步骤 2：第一次调用 LLM（消息 + 工具定义）
first_response = llm_with_tools.invoke(messages)
messages.append(first_response) # AIMessage，可能带 tool_calls

# 步骤 3：检查并处理 tool_calls
if first_response.tool_calls:
 for tool_call in first_response.tool_calls:
 # tool_call 是 {"name": ..., "args": ..., "id": ...}
 # 注意：args 在 LangChain 里已经是解析好的 dict
 function_name = tool_call["name"]
 function_args = tool_call["args"]

 if function_name in available_tools:
 try:
 result = available_tools[function_name].invoke(function_args)
 except Exception as e:
 result = f"Error executing function {function_name}: {e}"
 content = str(result)
 else:
 content = f"Error: Unknown function {function_name}"

 # 结果包成 ToolMessage，tool_call_id 关联原始请求
 messages.append(ToolMessage(
 tool_call_id=tool_call["id"], # 必须提供原始调用的 ID
 content=content,
 name=function_name,
 ))

 # 步骤 4：带着工具结果二次调用 LLM
 final_response = llm_with_tools.invoke(messages)
 print(final_response.content)
else:
 # 第一次响应就没有 tool_calls，说明 LLM 直接回答了
 print(first_response.content)

四个关键点：

first_response.tool_calls 是一个列表。这条消息同时涉及"创建用户"和"查天气"两件事，模型支持并行工具调用时，一次响应里会返回多个 tool_calls，循环逐个执行、逐个回填——并行工具调用的全部真相就这么多
tool_call["args"] 拿到的已经是解析好的 dict。原笔记在这里紧跟过一句 json.loads(...)——dict 传进 loads 会直接 TypeError，这句必须删掉。较老的单函数 function_call 格式里参数才是 JSON 字符串，两种格式混写最容易在这里翻车
ToolMessage 必须带 tool_call_id，LLM 靠它把结果和哪一次请求对应起来
二次调用时，发给 LLM 的是完整三段消息：HumanMessage（原始请求）+ AIMessage（带 tool_calls 的调用决定）+ ToolMessage（执行结果）。LLM 看到这三段，才能生成综合回复

把这段跑通之后再回头看 Agent 封装：create_agent / AgentExecutor / LangGraph 的 ToolNode，做的就是"第 3 步 + 第 4 步包进一个带停止条件的循环"——没有 tool_calls 就退出循环返回文本。手写一遍的意义就在这里：以后封装出问题，你知道往哪一层查。

3. 完整实战：天气助手 ReAct

现在把第 2 节手写的循环交给 LangGraph 工程化：用户用自然语言问某城市天气（示例支持上海和北京），应用自动判断是否调用天气工具，拿到结果后作答，并且记得住对话上下文。

这一节整体迁自我当时的天气助手实战笔记，代码分六段，每段跟着当时的知识点注解。

3.1 环境与依赖

安装（原笔记把 typing、os 也写进了 pip install——它们是标准库，不是 pip 包，这里已删掉）：

pip install langchain langgraph langchain_openai langchain_core

设置环境变量 DASHSCOPE_API_KEY，并做启动检查：

import os
if not os.getenv("DASHSCOPE_API_KEY"):
 raise ValueError("DASHSCOPE_API_KEY environment variable not set. Please set it before running.")

os.getenv 从环境变量读密钥，避免硬编码进代码。

3.2 工具定义：@tool

from langchain_core.tools import tool

@tool
def get_weather_updates(query: str) -> str:
 """
 查询城市当前天气 (Query current weather for a city)
 Use this tool to find out the current weather for a given city.
 """
 print(f"--- Tool 'get_weather_updates' called with query: {query} ---")
 query_lower = query.lower()
 if "上海" in query_lower or 'shanghai' in query_lower:
 return "now is 30 celsius, foggy"
 elif "北京" in query_lower or 'beijing' in query_lower:
 return "now is 20 celsius, sunny"
 else:
 return f"Weather information for {query} not available with this tool. Only Shanghai and Beijing are supported."

tools = [get_weather_updates]

知识点：

@tool 装饰器把普通函数转成 LangChain 工具，query: str 的类型提示和返回值提示都会进入工具描述
docstring 至关重要：LLM 根据工具名和 docstring 判断何时调用（工具能干什么）和怎么调用（query 参数该传什么）。描述含糊，调用就跟着含糊
工具内部目前是 mock 的假数据，实际应用中替换成真实天气 API 调用即可
tools = [get_weather_updates] 收进列表，后续绑定到 LLM

3.3 模型初始化与工具绑定

from langchain_openai import ChatOpenAI

model = ChatOpenAI(
 model="qwen-max",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 temperature=0
)

model_with_tools = model.bind_tools(tools)

知识点：

ChatOpenAI 虽然名字带 OpenAI，但通过 base_url + api_key 可以接任何 OpenAI 兼容服务，这里接 DashScope
temperature=0 让输出更确定，对需要精确调用工具的场景是稳妥选择
bind_tools(tools) 之后，LLM 在认为合适时返回的将不是纯文本，而是携带工具调用指令的 AIMessage

3.4 状态与节点

状态用第 1 节的 MessagesState——本质就是 messages: Annotated[list, add_messages]，每次节点返回 {"messages": [...]} 时自动追加。节点有两个，一个调模型，一个执行工具：

from langchain_core.messages import HumanMessage, AIMessage, ToolMessage
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode

tool_node = ToolNode(tools) # 预构建的工具执行节点

def call_model(state: MessagesState):
 messages = state["messages"]
 print(f"--- Calling model with {len(messages)} messages. Last message type: {type(messages[-1])} ---")
 response = model_with_tools.invoke(messages)
 return {"messages": [response]}

知识点：

ToolNode(tools) 是 LangGraph 的预构建节点：接收工具调用请求，执行对应工具，把输出包装成 ToolMessage 返回——第 2 节手写的那段 for 循环，它内部替你做了
call_model 是自定义的 Agent 节点：把当前全部消息历史交给绑定了工具的 LLM。LLM 能直接回答时返回普通 AIMessage；需要工具时返回带 tool_calls 属性的 AIMessage，其中包含工具名、参数和唯一的 tool_call_id
返回值封装成 {"messages": [response]}，由 MessagesState 自动追加进消息列表

3.5 条件边与图构建

from typing import Literal
from langgraph.graph import START, END
from langgraph.checkpoint.memory import MemorySaver

def should_continue(state: MessagesState) -> Literal["tools", END]:
 messages = state["messages"]
 last_message = messages[-1]
 # 最后一条消息是否是带工具调用请求的 AIMessage
 if hasattr(last_message, 'tool_calls') and last_message.tool_calls and len(last_message.tool_calls) > 0:
 print(f"--- LLM decided to use tools: {last_message.tool_calls} ---")
 return "tools" # 有工具调用，去 "tools" 节点
 print("--- LLM decided NOT to use tools. Ending. ---")
 return END # 没有，结束流程

workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model) # Agent 节点
workflow.add_node("tools", tool_node) # 工具节点
workflow.add_edge(START, "agent") # 入口

# 条件边：从 "agent" 出发，由 should_continue 的返回值决定去向
workflow.add_conditional_edges(
 "agent",
 should_continue,
 {
 "tools": "tools", # 返回 "tools" -> 去 "tools" 节点
 END: END # 返回 END -> 结束
 }
)
workflow.add_edge("tools", "agent") # 工具执行完，回到 "agent"

checkpointer = MemorySaver() # 内存检查点，保存对话状态
app = workflow.compile(checkpointer=checkpointer)

知识点：

tools -> agent 这条回边是整张图的灵魂：工具执行完回到 LLM，让它基于工具结果继续生成——这就是 ReAct（Reasoning and Acting）循环
MemorySaver 把每个线程（对话）的状态存在内存里，让对话有记忆；生产环境要换持久化存储（第 5 节展开）
compile(checkpointer=...) 把图定义转成可执行应用，同时接入状态持久化

3.6 执行：两轮对话

# 用字符串区分不同的对话线程
thread_id = "chat_thread_42"
config = {"configurable": {"thread_id": thread_id}}

print("\nInvoking for Shanghai...")
shanghai_input = {"messages": [HumanMessage(content="what's the weather in Shanghai?")]}
final_state_shanghai = app.invoke(shanghai_input, config=config)

if final_state_shanghai["messages"] and isinstance(final_state_shanghai["messages"][-1], AIMessage):
 print(f"Final response for Shanghai: {final_state_shanghai['messages'][-1].content}")

print("\nInvoking for Beijing (same thread)...")
beijing_input_message = HumanMessage(content="what's the weather in Beijing?")
# 第二次调用：同一个 thread_id，新消息自动追加到已有历史之后
final_state_beijing = app.invoke({"messages": [beijing_input_message]}, config=config)

if final_state_beijing["messages"] and isinstance(final_state_beijing["messages"][-1], AIMessage):
 print(f"Final response for Beijing: {final_state_beijing['messages'][-1].content}")

知识点：

thread_id 区分对话会话。配合 checkpointer，相同 thread_id 的调用共享同一段对话历史
第二次问北京天气时只传新的 HumanMessage——MessagesState 自动把它追加到上海那轮之后，LLM 处理北京问题时看得到之前的完整对话
final_state["messages"][-1].content 取最后一条 AI 消息，即最终回复

3.7 六步执行流程梳理

现在把 “what’s the weather in Shanghai?” 这句话输进去之后，图里到底发生了什么逐步拆开——这段是当初记这篇笔记时最值得留下的部分：

入口（agent 节点）
- call_model 被调用，model_with_tools.invoke 收到 [HumanMessage(content="what's the weather in Shanghai?")]
- LLM（qwen-max）分析输入和 get_weather_updates 的 docstring，判断需要调用这个工具，参数 query 应为 “Shanghai”
- LLM 返回带 tool_calls 的 AIMessage，例如 tool_calls=[ToolCall(name='get_weather_updates', args={'query': 'Shanghai'}, id='call_abc123')]
- call_model 返回 {"messages": [AIMessage_with_tool_call]}
条件路由（should_continue）
- 检查最后一条消息，发现有 tool_calls
- 返回 "tools"
工具执行（tools 节点）
- ToolNode 接收 tool_calls，找到 get_weather_updates，用参数 {'query': 'Shanghai'} 调用
- 工具执行，返回字符串 "now is 30 celsius, foggy"
- ToolNode 把结果包装成 ToolMessage(content="now is 30 celsius, foggy", tool_call_id='call_abc123')
- 返回 {"messages": [ToolMessage_with_result]}
返回 Agent（agent 节点）
- tools -> agent 的回边把流程带回 call_model，此时 state["messages"] 包含：
  1. HumanMessage(content="what's the weather in Shanghai?")
  2. AIMessage(..., tool_calls=[...])
  3. ToolMessage(content="now is 30 celsius, foggy", tool_call_id='call_abc123')
- LLM 看到原始问题、自己调用工具的决定、工具的执行结果，基于这些生成自然回复，例如 AIMessage(content="The current weather in Shanghai is 30 degrees Celsius and foggy.")
- call_model 返回 {"messages": [AIMessage_final_response]}
条件路由（should_continue）
- 检查最后一条消息（最终回复），没有 tool_calls
- 返回 END
结束
- 图执行结束，app.invoke 返回最终状态
- 代码从 final_state["messages"][-1].content 提取并打印最终回复
- MemorySaver 把包含这四条消息的完整状态存到 thread_id="chat_thread_42" 名下

后续问北京天气时，由于 thread_id 相同，call_model 的初始状态里就包含上海那四条消息，再加上新的 HumanMessage(content="what's the weather in Beijing?")——LLM 因此有上下文感知。

回头看这张图，它就是第 2 节手写循环的图化：agent 节点是"调 LLM"，tools 节点是"执行 tool_calls 并回填 ToolMessage"，should_continue 条件边是循环的停止条件。手写过一遍再看这里，每一层都能对上号。

3.8 收尾要点

工具定义（@tool）：docstring 是 LLM 理解工具的唯一入口
模型绑定（bind_tools）：让 LLM 知道有哪些工具可用
MessagesState：消息历史的自动追加
ToolNode：预置的工具执行器
条件边 + END：循环的出口
MemorySaver + thread_id：跨轮次的对话记忆

4. Map-Reduce：超长文本分段摘要

前两节都在聊 Agent 循环，换一个场景：文本长度超过模型单次上下文窗口，怎么做摘要？

经典解法是 Map-Reduce——大数据领域的老朋友，用在长文本摘要上正合适：

切片（Chunking）：把长文本切成模型一次吃得下的小块
映射（Map）：对每个块独立摘要，这一步天然可并行
规约（Reduce）：把所有小摘要合并，让模型做最后一次整合，产出连贯的最终摘要

LangGraph 适合表达这种多步骤工作流：状态在节点间流转，每一步做什么清清楚楚。完整代码：

import os
from typing import TypedDict, List

from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langgraph.graph import StateGraph, START, END

llm = ChatOpenAI(
 model="qwen-plus",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 temperature=0,
)

text_splitter = RecursiveCharacterTextSplitter(chunk_size=2000, chunk_overlap=200)

# 1. 图的状态：整个流程要跟踪的全部数据
class GraphState(TypedDict):
 text: str # 原始长文本
 chunks: List[str] # 切分后的文本块列表
 summaries: List[str] # 每个文本块的摘要列表
 final_summary: str # 最终的摘要

# 2. 节点：切分
def chunk_text_node(state: GraphState):
 print("--- 正在切分文本 ---")
 chunks = text_splitter.split_text(state['text'])
 return {"chunks": chunks}

# 3. 节点：Map，对每个块独立摘要
def summarize_map_node(state: GraphState):
 print("--- 正在对每个块进行摘要 (Map) ---")
 map_prompt = ChatPromptTemplate.from_template(
 "简要总结以下文本内容：\n\n{chunk}"
 )
 summarize_chain = map_prompt | llm

 # batch 并行处理所有块，max_concurrency 控制并发
 summaries = summarize_chain.batch(
 [{"chunk": chunk} for chunk in state['chunks']],
 config={"max_concurrency": 5}
 )
 # batch 返回 AIMessage 列表，提取 .content
 cleaned_summaries = [s.content for s in summaries]
 return {"summaries": cleaned_summaries}

# 4. 节点：Reduce，合并所有小摘要
def summarize_reduce_node(state: GraphState):
 print("--- 正在合并所有摘要 (Reduce) ---")
 summaries_joined = "\n\n".join(state['summaries'])

 reduce_prompt = ChatPromptTemplate.from_template(
 "你收到了关于一个长文档的多个摘要。请将它们整合成一个连贯、流畅、全面的最终摘要。\n\n"
 "以下是各个部分的摘要：\n{summaries_text}"
 )
 reduce_chain = reduce_prompt | llm
 final_summary = reduce_chain.invoke({"summaries_text": summaries_joined})
 return {"final_summary": final_summary.content}

# 5. 连图
workflow = StateGraph(GraphState)
workflow.add_node("chunker", chunk_text_node)
workflow.add_node("mapper", summarize_map_node)
workflow.add_node("reducer", summarize_reduce_node)

workflow.add_edge(START, "chunker") # 入口
workflow.add_edge("chunker", "mapper")
workflow.add_edge("mapper", "reducer")
workflow.add_edge("reducer", END)
app = workflow.compile()

# 6. 跑一个示例：把一段文本重复 10 次模拟长文本
long_text = """
人工智能（AI）正在以前所未有的速度改变世界。从自动驾驶汽车到医疗诊断，AI的应用无处不在。
其核心技术包括机器学习、深度学习和自然语言处理。机器学习使计算机能够从数据中学习规律，而无需进行显式编程。
深度学习是机器学习的一个分支，它利用深度神经网络模型，在图像识别、语音识别等领域取得了巨大成功。
自然语言处理则致力于让计算机能够理解和生成人类语言，Siri和ChatGPT就是最好的例子。
然而，AI的发展也带来了挑战，如数据隐私、算法偏见和就业冲击。解决这些问题需要技术、法律和伦理的共同努力。
""" * 10

final_state = app.invoke({"text": long_text})
print(final_state['final_summary'])

代码要点：

GraphState 是 TypedDict，像一份清单，规定流程要跟踪的全部数据（原文、块、各块摘要、最终摘要）。注意这里的字段没有 add_messages 这类 reducer——默认覆盖语义，每个字段只由一个节点整体写入一次，正好匹配这条线性流水线（对照 1.2 节）
chunk_text_node 是入口节点：接收 text，用 RecursiveCharacterTextSplitter 切分，chunks 写回状态
summarize_map_node 是 Map 步骤：batch() 并行为每个块生成摘要，比手写 for 循环高效；返回的 AIMessage 列表要取 .content
summarize_reduce_node 是 Reduce 步骤：小摘要拼接后交给 LLM 做最后一次、也是最关键的整合
边的连接定义流水线顺序：chunker -> mapper -> reducer -> END
invoke({"text": long_text}) 启动整张图——初始状态只需要 text 一个键，LangGraph 按定义好的流程执行完所有步骤，返回包含全部结果的最终状态

这套结构既绕开了上下文窗口限制，流程又清晰可维护：想加一步"摘要去重"或"质量过滤"，加个节点就行。

5. 记忆与持久化：MemorySaver 与 thread_id

第 3 节的天气助手已经用上了 MemorySaver，这里把机制单独拆开讲，因为它值得。

LangGraph 的记忆靠 checkpointer（检查点）机制：图每执行完一步，就把当前状态存一份快照。编译时传入 checkpointer，运行时指定 thread_id：

from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()
app = graph.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "1"}}
result = app.invoke({"messages": [HumanMessage(content="你好！")]}, config)

# 后续调用恢复状态：只传新消息，历史自动接上
result = app.invoke({"messages": [HumanMessage(content="继续聊")]}, config)

thread_id 是记忆的单位：同一个 thread_id 下的调用共享状态，换一个 thread_id 就是全新对话
MemorySaver 存在内存里，进程结束记忆就没了——适合开发和测试
生产环境要换持久化实现：官方提供了 SQLite、Postgres 等独立安装的 checkpointer 包，也可以自己接 Redis 这类存储

命名注记：这个类现在叫 InMemorySaver，MemorySaver 是保留的旧别名，两个名字指向同一个东西，新代码建议用前者。

6. LangGraph 1.1 / 1.2：从"能跑"到"敢上生产"

前五节的图，跑通没问题，但真接到线上会遇到几类很实际的问题：某个节点卡住了整张图跟着挂、某一步失败之后没有退路只能整个 run 报废、服务收到 SIGTERM 时正在跑的活儿全丢、长对话的 checkpoint 越存越大。1.1 和 1.2 基本就是冲着这些来的。

以下内容默认需要 langgraph>=1.2；6.7 那节是 1.1 引入的。

6.1 节点超时：`TimeoutPolicy`

add_node 现在接受 timeout=，给单次节点尝试封顶：

from datetime import timedelta
from langgraph.types import TimeoutPolicy

# 简单封顶：秒数或 timedelta
builder.add_node("call_model", call_model, timeout=60)
builder.add_node("call_model", call_model, timeout=timedelta(minutes=2))

# 分别限制总时长和空闲时长
builder.add_node(
 "call_model",
 call_model,
 timeout=TimeoutPolicy(run_timeout=120, idle_timeout=30),
)

两种限制的语义不一样，别混用：

run_timeout 是硬性挂钟上限，永不刷新。不管节点多活跃，到点就砍——适合"这个调用最多花两分钟"这种业务约束。
idle_timeout 是随进度重置的上限。只在节点一段时间内没有任何可观测进展时才触发——适合"卡死检测"。还能配 refresh_on="heartbeat" 用心跳当进度信号。

两个值可以同时给。超时后 LangGraph 抛 NodeTimeoutError，清掉这次失败尝试写入的状态，然后交给重试策略决定要不要重试。NodeTimeoutError 默认是可重试的，而且超时时钟每次重试重新计时，所以 timeout 和 retry_policy 放在一起是开箱可用的。

有个容易踩的坑：节点超时只对 async 节点生效。同步节点带 timeout 会在编译期就被拒绝。要包阻塞式 I/O，得在 async 节点里用 asyncio.to_thread。

6.2 节点级错误处理：`error_handler`

重试解决的是"偶发失败"，但有些失败重试三次也还是失败，这时候你需要的是退路而不是重试。add_node 的 error_handler= 就是干这个的：它在节点失败且重试耗尽之后执行，拿到当前状态，可以改状态，也可以用 Command 跳到别的节点。

from langgraph.errors import NodeError
from langgraph.types import Command, RetryPolicy

def charge_payment(state: State) -> State:
 raise RuntimeError("payment gateway timeout")

def payment_error_handler(state: State, error: NodeError) -> Command:
 return Command(
 update={"status": f"compensated: {error.error}"},
 goto="finalize",
 )

graph = (
 StateGraph(State)
 .add_node(
 "charge_payment",
 charge_payment,
 retry_policy=RetryPolicy(max_attempts=3, retry_on=ConnectionError),
 error_handler=payment_error_handler,
 )
 .add_node("finalize", finalize)
 .add_edge(START, "charge_payment")
 .compile()
)

这就是 Saga / 补偿模式的表达方式：失败不是把整张图炸掉，而是走一条补偿路径把状态收拾干净。

几个细节：

执行顺序是固定的——先重试，重试耗尽（或没配重试策略）才轮到错误处理器。两者解耦，可以分别配。
想拿到失败上下文，就把参数标注成 error: NodeError（按类型注解注入，和 runtime: Runtime 一个套路）。NodeError 是 frozen dataclass，只有两个字段：node（失败的节点名）和 error（原始异常）。
不需要上下文的话，签名写成 (state) 或 (state, runtime) 也行。
注入是可选的，但每个节点最多一个 error_handler。

6.3 图级默认值：`set_node_defaults`

如果每个节点都要重复写一遍 retry_policy= / error_handler= / timeout=，代码会很难看。set_node_defaults 把这些提成图级默认：

from langgraph.types import RetryPolicy, TimeoutPolicy

builder = (
 StateGraph(State)
 .set_node_defaults(
 error_handler=default_error_handler,
 timeout=TimeoutPolicy(run_timeout=30),
 )
 .add_node("step_a", step_a) # 用默认处理器
 .add_node("step_b", step_b, error_handler=custom_error_handler) # 用自己的
)

这个能力在"每次图运行都对应一个外部进程"的场景下特别值——比如后台任务表里的一行，任何未处理的节点失败都应该把那行标成 failed，不用在每个 add_node 上重复声明。单节点配置优先于图级默认值。

有个安全设计要注意：错误处理器节点本身不套用 error_handler 默认值——处理器不能接住自己，否则就是无限递归。

6.4 优雅停机：`RunControl` 与 drain

服务要重启、容器要缩容，收到 SIGTERM 时正在跑的图怎么办？1.2 给了一个协作式的停机机制：跑完当前 superstep 再停，并保存一个可恢复的 checkpoint。

import signal
from langgraph.runtime import RunControl
from langgraph.errors import GraphDrained

control = RunControl()
signal.signal(signal.SIGTERM, lambda *_: control.request_drain("sigterm"))

try:
 result = graph.invoke(inputs, config, control=control)
except GraphDrained as e:
 log.info("graph drained: %s", e.reason)
 # 下次启动时用同一个 config 继续

drain 的语义是"协作"，它只在 superstep 之间生效，绝不抢占已经在跑的工作：

场景	行为
节点执行到一半	跑完。drain 在下一个 superstep 生效
节点正在按重试策略重试	重试循环跑到成功或耗尽，之后才生效
图正好在同一次 tick 自然结束	正常返回。用 `control.drain_requested` 区分
后面还有 superstep	抛 `GraphDrained(reason)`，checkpoint 已保存可续跑
子图请求 drain	`GraphDrained` 向上冒泡，让父图在它自己的下一个边界停

节点内也能感知 drain，用来跳过昂贵的工作：

from langgraph.runtime import Runtime

async def my_node(state: State, runtime: Runtime) -> State:
 if runtime.drain_requested:
 return {"status": "skipped", "reason": runtime.drain_reason}
 return {"status": await do_work()}

恢复就是同一 thread_id 下 graph.invoke(None, config)。

别把它当成强制中断：request_drain() 不会取消正在跑的 asyncio task，也不会杀线程。想要硬上限，得把 drain 和一个 grace timeout + 任务取消配合使用。

6.5 DeltaChannel：给长线程的 checkpoint 减重

图跑得越久，checkpoint 越大。原因是消息列表这类 channel 每步都在增长，而过去的做法是每一步都把累积后的全量值重新序列化进 checkpoint——于是存储和读取延迟随对话长度线性上升。

1.2 引入的 DeltaChannel（beta）只存每一步写入的增量，不存全量。对消息列表这种只会越堆越长的 channel，效果最明显。代价是读历史要重放 delta，所以可以配 snapshot_frequency=K，每 K 步写一次全量快照给读取延迟封顶。

如果你在用 DeepAgents，注意它从 0.6.0 起也把消息历史和 agent 文件切到了 DeltaChannel，而且这个变更不可回滚——细节见《DeepAgents完全指南》3.5 节。

6.6 流式输出换代：事件流（v3）

stream_mode="messages" / "updates" 那套是 LangGraph 的原始流式接口，拿到的是 dict，得自己判断这块是什么。1.2 起多了一层更适合应用代码的东西——事件流，传 version="v3" 开启：

stream = graph.stream_events(input_data, version="v3")

for message in stream.messages: # token 级模型输出
 print(str(message.text), end="", flush=True)

final_state = stream.output # 最终状态

它的关键设计是：一次 run 的事件流被归一化成几个带类型的投影，多个消费者可以同时读——读 stream.messages 不会消耗 stream.values 需要的事件。可用的投影有 stream.messages、stream.values、stream.output、stream.subgraphs、stream.interrupts / stream.interrupted，以及给自定义 transformer 用的 stream.extensions。

异步并发读用 asyncio.gather；同步代码想按严格到达顺序混读多个投影，用 stream.interleave("values", "messages", "subgraphs")。

底层 messages 通道是按 content block 建模的，事件序列固定为 message-start → content-block-start → content-block-delta → content-block-finish → message-finish，文本、推理、工具调用、多模态内容都有显式边界，不再依赖各家 provider 的格式。

v1 / v2 保持兼容，没有破坏性变更——老代码不用动，新代码建议直接从 v3 起步。

6.7 类型安全的 invoke / stream（1.1）

1.1 就往这个方向走了一步：invoke() / stream() 传 version="v2" 会拿到带类型的东西。

from langgraph.types import GraphOutput

result: GraphOutput = graph.invoke(input_data, config, version="v2")
print(result.value) # 状态值
print(result.interrupts) # 中断信息

stream(..., version="v2") 则统一输出带 type / ns / data 三个键的 StreamPart，每种 mode 一个 TypedDict，都能从 langgraph.types 导入。另外 version="v2" 下，invoke() 和 values mode 的输出会自动转换成你声明的 Pydantic 模型或 dataclass 类型。

version="v2" 是 opt-in，GraphOutput 也保留了废弃的 dict 风格访问，方便渐进迁移。

7. 版本注记：从 0.x 写法到 LangChain 1.x

这篇整合自 0.x 时代的笔记，几处新旧差异统一交代：

set_entry_point 已统一为 add_edge(START, ...)。原笔记的天气助手和 Map-Reduce 图用的都是 set_entry_point("agent") 这类写法，官方后来统一成 add_edge(START, "agent")（连同 set_finish_point → add_edge(node, END)），本文正文已全部改写。旧写法当前仍可用，但属废弃路径
ChatTongyi 属 legacy。原笔记另一处用 langchain_community.chat_models 的 ChatTongyi 直连通义——这个包里的集成属于 legacy。本文统一走 DashScope 的 OpenAI 兼容端点（ChatOpenAI + base_url），这也是当时验证过可行的路线
模型。原笔记示例里有 gpt-3.5-turbo（已下线）和 gpt-4o-mini，整合时统一替换为 DashScope 的 qwen-plus / qwen-max
一行式封装。现在构建 ReAct Agent 不需要手搓图：langgraph.prebuilt.create_react_agent 一行拉起；LangChain 1.x 的 langchain.agents.create_agent 是官方标准入口，底层就是 LangGraph。但我的判断是：手写一遍第 2 节那个循环，仍然是理解这些封装的最佳方式——封装出问题时，你得知道问题出在哪一层
MemorySaver → InMemorySaver（见第 5 节）。旧名仍是可用别名，但新代码建议用 InMemorySaver
1.1 / 1.2 是增量而非破坏性变更。第 6 节的超时、错误处理器、优雅停机、DeltaChannel、事件流都是 opt-in 的新参数或新 API，老代码不改也能继续跑。注意 timeout / error_handler / 优雅停机需要 langgraph>=1.2

版本基线

组件	本文参考版本	备注
`langgraph`	1.2.11（2026-08-11）	1.2.0 起有超时 / 错误处理 / 优雅停机 / 事件流
`langgraph-checkpoint`	4.2.0	`DeltaChannel` 相关修复在这个线上
`langgraph-sdk`	0.4.4	走 Agent Server 时用
`langchain`	1.4.0	`create_agent` 入口；MCP 已内建为 `langchain.mcp`

更深的 Agent 工程化路线——多智能体、子智能体、规划与上下文管理——同目录的《DeepAgents完全指南》是这篇的自然延伸。

参考：LangGraph 官方文档、容错与优雅停机、事件流

附：题外话——我试过的 LangChain 知识图谱（不是 LangGraph）

如实交代：写《Langchain-Graph实战教程》那篇笔记时，我把两个 “Graph” 搞混了——LangChain 的 Knowledge Graph 功能和 LangGraph 是完全不同的东西。前者（GraphQAChain、NetworkXEntityGraph、LLMGraphTransformer）用图结构表示知识、做图谱问答；后者是工作流编排框架。一个是数据，一个是执行引擎。

不过那次实验的踩坑记录值得留档。当时用 LLMGraphTransformer（langchain_experimental）从文本构建内存知识图谱，写法如下（Tongyi 同样来自 langchain_community，属当时的旧写法）：

from langchain_community.llms import Tongyi
from langchain_community.graphs import NetworkXEntityGraph
from langchain_experimental.graph_transformers.llm import LLMGraphTransformer
from langchain_core.documents import Document

llm_for_graph = Tongyi(model_name="qwen-plus")

document_content = """
张三是北京大学的教授，他研究人工智能领域。
李四是张三的学生，他就读于清华大学，学习计算机科学。
王五是百度的工程师，百度是一家位于北京的科技公司。
"""
docs = [Document(page_content=document_content)]

llm_transformer = LLMGraphTransformer(llm=llm_for_graph)
graph_documents = llm_transformer.convert_to_graph_documents(docs)

final_graph = NetworkXEntityGraph()
final_graph.add_graph_documents(graph_documents)
for triple in final_graph.get_triples():
 print(triple)

两个结论：

GraphQAChain 对 NetworkXEntityGraph 支持不佳。当时直接 graph_qa_chain.run(question) 基本走不通——它内部按生成 Cypher 查询的思路工作，而内存图根本不支持 Cypher，一跑就抛错
手工三元组检索是可用的备选。绕开 Chain，直接从图里捞相关三元组当上下文，交给 LLM 回答：

def get_relevant_triples(graph, entity_name):
 """检索与某个实体相关的三元组"""
 lines = []
 for s, p, o in graph.get_triples():
 if entity_name in str(s) or entity_name in str(o):
 lines.append(f"({s}, {p}, {o})")
 return "\n".join(lines)

context = get_relevant_triples(final_graph, "张三")
# 再把 context 和问题拼进 prompt，交给 LLM 生成答案

另外说明：LLMGraphTransformer 至今还在 langchain_experimental 里，仍属实验性，别在生产上依赖它。我的判断：真要做知识图谱问答，直接上 Neo4j 配 GraphCypherQAChain；或者更轻的做法——三元组检索本质上就是 RAG 的一种上下文来源，没必要被"图谱"这个词吓住。

总结

LangGraph 的地基是三件套：StateGraph（状态机）、State（reducer 决定覆盖还是追加）、条件边（动态路由）。MessagesState 只是 Annotated[list, add_messages] 的官方打包
Agent 没有魔法：tool_calls → 执行 → ToolMessage 回填 → 二次调用，一行式封装做的就是在消息列表上转这一圈
ReAct 循环的图表达就三个部件：agent / tools 节点、should_continue 条件边、tools -> agent 回边
超出上下文窗口的活交给 Map-Reduce，图让流水线每一步可插拔
记忆的单位是 thread_id + checkpointer，内存版叫 InMemorySaver
上线前补齐三件事：timeout= 防卡死（注意只对 async 节点生效）、error_handler= 给失败留退路（Saga 补偿）、RunControl + drain 应对停机。重复的配置用 set_node_defaults 提到图级
长线程的 checkpoint 膨胀用 DeltaChannel 解决；应用层读流式输出优先用 version="v3" 的事件流，投影带类型且可多消费者并发读

先手写一遍循环、看懂消息怎么流，再谈一行式封装——这是全文的路线，也是我判断的入门 LangGraph 最不绕的路。

一个订阅更新摘要 Agent 的完整实践：从提示词踩坑到长文本分块

Tue, 08 Sep 2026 12:00:00 +0800

一个订阅更新摘要 Agent 的完整实践：从提示词踩坑到长文本分块

本文整合自同一个项目的三篇旧文（2025 年 3 月–4 月），代码、截图、结论都来自当时的真实记录，合并时只做整理和勘误，没有补写任何"当时应该是这样"的情节——包括没起作用的 memory。文中 ConversationSummaryBufferMemory 等 legacy memory API 已在 LangChain 1.0 移除，相应位置有版本注记，核心思路不受版本影响。

2025 年 3 月，我给自己做了一个订阅系统的 agent：定期抓取订阅的网站，对比前后两次抓到的内容，把 diff 交给 LLM，让它总结"这段时间到底更新了什么"，输出一份固定格式的 JSON 摘要（概要、关键点、字数、生成时间）。项目不大，一个月里却把 agent 开发最常见的两类坑各踩了一遍——提示词的坑，和长文本的坑。

先把两个贯穿全文的判断放在前面：

对人类差不多的提示词，对 agent 是天壤之别。 把"仅仅是时间的变化"扩成"时间或者数据的变化"，几个字的改动，让同一批模型、同一类数据上的输出从"全是噪音"变成"基本可用"。
超长文本靠 map-reduce 式分块，不靠记忆机制。 diff 超出 token 上限时，按变更单元切块、逐块抽取、最后汇总——朴素，但真的解决问题。中间版本引入过的"记忆机制"，如后文坦白，在实际代码路径里基本是装饰。

全文按时间线组织：第一节是第一版管线的完整代码；第二节是提示词踩坑与迭代的全过程，含双模型前后对照截图；第三节是超长 diff 的分块处理；第四节把散在代码里的工程取舍集中成一份清单。

一、第一版管线：从 PromptTemplate 到 JSON 解析

输入与输出

业务的输入只有一样东西：contentdiff——前后两次抓取的差异文本，形如：

"Changed: '旧文本' -> '新文本'", "Added: '新增的段落'", "Deleted: '被删掉的段落'"

由于文本长度的限制，历史全文不可能都给模型，只给当前这次更新的差异。输出是固定结构的 JSON，先用一个 dict 把形状定下来：

SUMMARY_TEMPLATE = {
 "summary": {
 "content": "",
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 },
 "status": "success",
 "error_message": None
}

SubscriptionAgent：提示、组链、解析

第一版的完整骨架。LLM 来自项目内部模块 src.agent.llm 的 get_ali_llm——它做的事就是返回一个 LangChain 兼容的模型实例，等价写法附在本节末尾：

from langchain.prompts import PromptTemplate
import json

from src.agent.llm import get_ali_llm


class SubscriptionAgent:
 def __init__(self, llm_model=None):
 self.llm = llm_model if llm_model else get_ali_llm("qwen-7b-chat")
 # 冒烟测试：先 invoke 一句"你好"，确认 LLM 连得上
 print(self.llm.invoke("你好"))

 self.prompt_template = PromptTemplate(
 input_variables=["contentdiff"],
 template="""
 你是一个订阅号运营专家，可以根据差异内容总结出订阅内容的更新情况，请对以下内容差异进行总结：
 {contentdiff}

 要求：
 1. 提供简洁的内容更新概要
 2. 提取关键点
 3. 计算总字数
 返回结果使用中文

 返回格式json（请严格按照以下格式返回）：
 {{
 "summary": {{
 "content": "",
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 }},
 }}
 """
 )

 self.chain = self.prompt_template | self.llm

三个点值得停下来看：

PromptTemplate 用 input_variables 声明动态变量，模板里 {contentdiff} 占位。要留心 JSON 花括号必须写成 {{ }} 转义，否则会被当成变量占位符。
self.prompt_template | self.llm 就是 LCEL 的组链写法：| 两侧只要是 Runnable，拼起来就是一条链。invoke 时 PromptTemplate 先把变量填进模板，产出的字符串直接喂给 LLM，返回一个带 .content 的消息对象。0.1 之前要写 LLMChain(prompt=..., llm=...)，现在一行管道就替代了。
invoke 的输入是字典，key 必须和 input_variables 匹配——传 {"contentdiff": ...}，不是裸字符串。

解析和兜底在 generate_summary 里：

 def generate_summary(self, contentdiff: str) -> dict:
 try:
 result = self.chain.invoke({"contentdiff": contentdiff}).content

 parsed_result = json.loads(result)
 summary_content = parsed_result["summary"]["content"]
 key_points = parsed_result["summary"]["key_points"]
 word_count = parsed_result["summary"]["word_count"]
 generated_at = parsed_result["summary"]["generated_at"]

 response = SUMMARY_TEMPLATE.copy()
 response["summary"]["content"] = summary_content
 response["summary"]["key_points"] = key_points
 response["summary"]["word_count"] = word_count
 response["summary"]["generated_at"] = generated_at
 return response

 except Exception as e:
 error_response = SUMMARY_TEMPLATE.copy()
 error_response["status"] = "error"
 error_response["error_message"] = f"Error on line {e.__traceback__.tb_lineno}: {str(e)}"
 return error_response

流程很直白：跑链、json.loads 直解、把字段填进模板；任何一步炸了就整体降级成 status="error" 的结构返回，不向上抛异常。这里有个隐患：SUMMARY_TEMPLATE.copy() 是浅拷贝，嵌套的 summary 字典是共享的——当时没暴露问题，是因为成功路径每次都把四个字段全覆盖了一遍。复用这段代码的话，用 copy.deepcopy 或者每次构造新 dict 更稳。

用一段玩具 diff（“The quick brown fox jumps over the lazy dog” 那种）喂进去，跑通的输出长这样（原文记录的示例）：

{
 "summary": {
 "content": "内容从'quick'改为'swift'，'jumps'改为'leaps'，新增'quickly'。",
 "key_points": ["quick -> swift", "jumps -> leaps", "新增 quickly"],
 "word_count": 18,
 "generated_at": "2025-03-13T10:00:00"
 },
 "status": "success",
 "error_message": null
}

get_ali_llm 的等价写法——任何 OpenAI 兼容端点都适用（这也是项目后期脚本里的实际写法）：

from langchain_openai import ChatOpenAI
import os

def get_ali_llm(model: str = "qwen-7b-chat"):
 return ChatOpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 model=model,
 )

当时已知的软肋与对策

第一版最明显的软肋是 LLM 不一定严格按 JSON 格式返回。当时的对策有三条：

解析器上链。 把 SimpleJsonOutputParser 挂在链尾，输出自动解成 dict，不用再手写 json.loads：

from langchain_core.output_parsers.json import SimpleJsonOutputParser

self.chain = self.prompt_template | self.llm | SimpleJsonOutputParser()
result = self.chain.invoke({"contentdiff": contentdiff})

重试。 LCEL 的 Runnable 自带 .with_retry()：

result = self.chain.with_retry(stop_after_attempt=3).invoke({"contentdiff": contentdiff})

后来实际落地时用的是外层循环重试（第三节脚本里的写法），重试间隔和日志更好控制，两种都可行。

异步。 同步 invoke 在高频场景是瓶颈，链本身支持 ainvoke，接口不用改。

管线能跑，只说明"能返回 JSON"；JSON 里装的是不是想要的内容，是另一回事——这就是下一节踩的坑。

二、提示词踩坑：一字之差的质变

我之前一直认为，只要模型好，提示词随便写一写，模型都能返回差不多的内容。实际上，对于人来说是差不多的，因为人的大脑可以进一步理解内容。但是，如果开发 agent 就不一样了！！！

这段话是当时记下的，现在仍然是我对提示词工程最重要的体会。这节把整个过程原样重放一遍。

误判现场

当时我在开发这个订阅系统的 agent，任务是给它一些内容，让它总结这段时间更新了什么。由于文本长度的限制，不可能把历史文本都给它，只给当前更新的差异。

然后遇到了一个问题，对于下面的差异文本：

"[""Changed: '53 分钟' -> '1 小时'"", ""Changed: '1' -> '2'"", ""Changed: '3' -> '4'"", ""Changed: '3' -> '4'"", ""Changed: '4' -> '5'"", ""Changed: '4' -> '5'""]"

人一眼就能看出来，这个内容实际上是没有变化的，因为变化的只不过是网站上内容的间隔时间，但是 agent 却认为有变化。 我的提示词如下写道——这版已经带上了"注意"段，专门提醒模型忽略纯时间变化（第一版连这个都还没有）：

你是一个订阅号运营专家，可以根据差异内容总结出订阅内容的更新情况，请对以下内容差异进行总结：
 {contentdiff}

 注意，有些内容的更新可能仅仅是由于时间的变化，比如[""Changed: '33' -> '40'"", ""Changed: '58 分钟' -> '1 小时'""]，这样的内容更新是不需要总结的，可以看作没有更新

 要求：
 1. 提供简洁的内容更新概要
 2. 提取关键点
 3. 计算内容的列表长度
 返回结果使用中文,如果内容更新或者没有关键点，请返回空数组。
 请根据以上要求，总结出订阅内容的更新情况，并返回结果。


 返回格式json（请严格按照以下格式返回）：
 {{
 "summary": {{
 "content": [],
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 }},
 }}


 """

然后看 qwq-32b 和 grok3 的输出：

可以看到他们都没给我想要的输出——我想要的就是一个空的数组，因为没有更新，但它们给我返回的是……

关键改动

然后我把提示词改成这样：

你是一个订阅号运营专家，可以根据差异内容总结出订阅内容的更新情况，请对以下内容差异进行总结：
 {contentdiff}

 注意，有些内容的可能仅仅是时间或者数据的变化，这样的内容更新是不需要总结的，可以看作没有更新，返回空数组

 要求：
 1. 提供简洁的内容更新概要
 2. 提取关键点
 3. 计算内容的列表长度
 返回结果使用中文,如果内容更新或者没有关键点，请返回空数组。
 请根据以上要求，总结出订阅内容的更新情况，并返回结果。


 返回格式json（请严格按照以下格式返回）：
 {{
 "summary": {{
 "content": [],
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 }},
 }}

就这一点点的改动：

注意，有些内容的可能仅仅是时间或者数据的变化，这样的内容更新是不需要总结的，可以看作没有更新，返回空数组

但是效果：

我感觉没什么问题。

第二轮：真实 diff 再验证

再来试试其他的——这次直接上真实抓取的 diff，数据原样贴出（它也是第三节要处理的"超长输入"的真实模样）：

你是一个订阅号运营专家，可以根据差异内容总结出订阅内容的更新情况，请对以下内容差异进行总结：
 "[""Changed: '2' -> '33'"", ""Changed: 'Fl' -> 'Andr'"", ""Changed: 'we' -> 'id Studio集成Gemini新增多模态功能，开发者可上传图像获取UI代码\n谷歌最新宣布，And'"", ""Changed: ' Labs 颠覆AI' -> 'oid Studio中的Gemini助手已升级支持多模态输入功能，开发者现在可以直接将图像附加到提示中，以获取'"", ""Added: '程序开发过程中的视觉辅助。这项多'"", ""Added: '态功能最初在I/O2024大会上亮相，升级后的Gemini现能够\""理解简单的线框，并将其转换为可用的Jetpack Compose代码\""。在Android Studio Narwal的Canary版本中，Ask Gemini字段新增了\""附加图像文件\""（支持JPEG或PNG格'"", ""Changed: '，2' -> '）选项。谷歌建议用户使用具有\""强烈色彩对比\""的图像并提供\""清晰的提示\""以获得最佳效果。开发者可以上传从简单线框到高保真模型\n58 分钟前\n.\nAIbase\n北京新增'"", ""Changed: '60万美元打造首个全开放混合计算平台\n' -> '4款已完成登记的生成式AI服务，小米AI搜索、Monica在列\n网信北京发布了最新北京市生成式'"", ""Changed: '正在以前所未' -> '服务已登记信息公告，公称，根据《生成式人工智能服务管理暂行办法》及'"", ""Changed: '的速度融入我们的日常' -> '关规定，对于通过API接口或其他方式直接调用已备案大模型能力的生成式人工智能'"", ""Changed: '，而一家名为Flower Labs的初创公司正以革命性的' -> '或功能，采用登记管理'"", ""Changed: '改变AI模型的部署和运行方' -> '，允许上线提供服务。截至3月14日，我市新增34款已完成登记的生成'"", ""Changed: '。这家获得Y C' -> '人工智能服务，累计已完成46款生成式人工智能服务登记。其中，小米AI搜索、小米AI写作、M'"", ""Changed: 'mb' -> 'n'"", ""Deleted: 'nator支持的新锐企业近日推出了Flower Intelligen'"", ""Changed: 'e，一个创新的分布' -> 'a等产品在列。已上线的生成'"", ""Deleted: '云平台，专为在移动设备、个'"", ""Changed: '电脑和网络' -> '工智能'"", ""Added: '或功能，应在显著位置或产品详情页面，公示所取\n1 小时前\n.\nAIbase\n阿里通义实验室语音团队负责人鄢志杰离职\n据tech星球消息，阿里通义实验室语音团队负责人鄢志杰已于 2 月 15 日正式离职，其职级为阿里原P序列体系'"", ""Changed: '提供AI模型服务而设计。Flower Intelligence的核心优势在于其独特的混合计算策略。该平台允许应用程序在本地设备上运行AI模型，既保证了速度，又增强了隐私保护。当需要更强大的计算' -> '的P10 级别。鄢志杰是智'"", ""Changed: '力时，系统会在获得用户同意的情况下，无\n7 分钟前\n.\nAIbase\n调查：5' -> '语音领域专家， '"", ""Changed: '%美国成' -> '003 '"", ""Changed: '人使用过AI聊天机器人\n美国埃隆大学的一项调查显示，52%的美国成年人都曾使用过像ChatGPT、Gemini、Claude这样的AI' -> '进入中科'"", ""Changed: '言模型。这项由北卡罗来纳州埃隆' -> '音实验室攻读博士，师从科'"", ""Changed: '学“想象数字未来中心”在1月份开展的调查，选取了5' -> '讯飞创始人王仁华教授。 2'"", ""Changed: '名受访者。结果' -> '8 年获博士学位后，他在微软亚洲研究院语音组担任主管研究员至 2015 年，主要研究语音识别、语音合成等领域。学术上，他'"", ""Deleted: '现，在使用过AI的人群中，34%的人'"", ""Changed: '示至少每天会使用一次大语言模型。其中，ChatGPT最受欢迎，72%的受访者都用过;谷歌的Gemini位居第二，使用率为50% ' -> '多篇顶级论文，拥有多项专利'"", ""Deleted: '越来越多的人开始和AI聊天机器人建立起特殊的关系。调查显示，38%的用户认为大语言模\n'"", ""Changed: '7 分钟前\n.\nAIbase\n北京将在中小学打造' -> '0'"", ""Changed: '1个人工' -> '5 年加入阿里巴巴后，鄢志杰曾担任IDST'"", ""Changed: '应用场景，启动7个\""京娃\""智能体\n据央视新闻报道，北京市教委宣布，今年将在中小学重点打造首批' -> '语音交互\n'"", ""Changed: '1个人工智能应用场景，并启动培育建设7个\""京娃\""智能体，旨在以人工智能技术赋能五育融合培养体系，助力学生个性化、多样化发展。这些应用场景涵盖了\""AI助教\""的智能备课、智能课堂质量监测、智慧作业/命题;\""AI助学\""的智能错题分析及资源推荐、自主写作批改、外语学习助手;\""AI助育\""的智慧体育、心理健康助手;\""AI助评\""的智慧综合素质评价;\""AI助研\""的智能教师专业发展平台;以及\""AI助管\""的智慧校园。随着场景落地，7个各具\n39 分钟前\n.\nAIbase\n百万成本揭秘LLM训练黄金法则，阶跃星辰推出全领域适用的超参数优化工具\n在人工智能的激烈竞争中，一场耗资百万美元的大规模实验正悄然改变着大语言模型的训练方式。阶跃星辰研究团队日前发布重磅研究成果，他们通过耗费近100万NVIDIA H800GPU' -> ' '"", ""Deleted: '的算力，从零开始训练了3，700个不同规模的模型，累计训练了惊人的100万亿个token，揭示出一条被称为\""Step Law\""的普适性缩放规律，为大语言模型的高效训练提供了全新指南。这项研究不仅仅是对超参数优化的探索，更是第一个全面考察模型最优超参在不同形状、稀疏度和数据分布下稳定性的工作。研究结果表明，无\n55 分钟'"", ""Changed: 'AI“天眼”再进化！YOLOE破壳而出：' -> '论文阅读噩梦'"", ""Deleted: '物体检测“刻板印象”，万物皆可实时识别'"", ""Changed: '\n曾几何时，AI的“眼睛”还带着厚重的“滤镜”，只能识别预设好的“剧本”。 但现在，游戏规则彻底改写! 一种名为YOLOE的全新AI模型破空问世，它像一位打破枷锁的“视觉艺术家”，挥别了传统物体检测的“僵化教条”，宣告了一个“万物皆可实时识别”的全新纪元! 想象一下，AI不再需要“死记硬背”类别标签，而是像人类一样，仅凭文本描述、模糊图像，甚至在毫无线索的情况下，就能“秒懂”眼前的一切。 这种颠覆性的突破，正是YOLOE带来的震撼变革!YOLOE的' -> 'AI神器'"", ""Changed: '，宛' -> '： arXiv论文一键变博客，科研效率火箭式飙升！\n你是否还在论文的海洋里苦苦挣扎?面对学术网站 arXiv 上堆积'"", ""Changed: '给AI装上\n1' -> '山的论文，是不是也感到头皮发麻，无从下手? 那些晦涩难懂的术语，曲折冗长的段落，复杂烧脑的图表，简直像一道道 impenetrable 的高墙，将求知的心牢牢阻隔在外。 对于科研爱好者、莘莘学子，甚至是专业人士来说，啃下一篇论文，往往需要耗费数小时的精力，甚至要查阅海量资料才能勉强摸到门道，这效率，简直让人抓狂!但!是! 所有挣扎，都将成为过去式! 一款横空出世的AI神器—— alphaXiv，要来彻底拯救你于论文苦海!\n3'"", ""Changed: '英国首相计划' -> '一男子因'"", ""Changed: 'AI替代部分公务员工作\n英国' -> ' AI 撰写色情小说被判刑十个月，非法获利超两万元\n近期，湖北省大冶市人民法院对一起'"", ""Changed: '相基尔・斯塔默（Keir Starmer）近日提出了一项新的计划，旨在通过数字化和' -> '例利用'"", ""Deleted: '来提高政府工作的效率。他将在周四的演讲中详细阐述这一构想，表示希望能够在公务员的工作中，尽可能地用数字化和 AI 替代那些可以以相同标准完成的任务。他强调，公务员的时间应该优先用于更需要人类判断和创造力的工作。斯塔默认为，英国政府通过更广泛地采用数字化方法，可以在未来节省超过 450 亿英镑的开支，并计划招募 2000 名新的'"", ""Changed: '学' -> '撰写色情小说并进行牟利的案件作出判决。被告人柯某因制作、贩卖、传播淫秽物品牟利罪，被判处有期'"", ""Changed: '来充实公务员队伍。他表示，这些措\n1 小时前\n.\nAIbase\n英矽智能完成1.1亿美' -> '刑十个月，并处罚金人民币五千'"", ""Changed: 'E轮融资 推动AI平台升级\n今日，英矽智能，一家专注于生成式人工智能技术的生物医药科技公司，正式对外宣布，已成功完成1.1亿美元的E轮融资。本轮融资由惠理集团（HKG:0806）旗下的私募股权基金、浦东创投、浦发集团、锡创投以及宜兴国控联合领投。此外，' -> '，退'"", ""Changed: '有多位专注于行业和科技领域的新晋投资者参与本轮融资，同时' -> '违法所'"", ""Changed: '到了现有投资者的鼎力支持。\n1 小时前\n.\nAIbase\n报道称MiniMax 意向收购AI视频创业公司鹿影科技\n' -> '。'"", ""Changed: '蓝鲸新闻独家消息' -> '公诉机关的'"", ""Changed: '出，人工智能视频初创公司鹿影科技（Avolution.ai）或将被知名人工智能公司MiniMax收购。据多位知情人士透露，双方已就收购达成初步意向，相关流程正在进行中。截至发稿，MiniMax尚未对此消息做出回应。据悉，鹿影科技' -> '控，柯某'"", ""Changed: '4' -> '2'"", ""Deleted: '天使轮融资时的估值约为'"", ""Changed: '亿人民币左右，低于2000万美元。知情人士表示，鹿影科技自去年起寻求第二轮融资并不顺利，而其在AI视频领域的技术积累最终促成了与MiniMax的合作，这被认为是双赢的选择。公开资料显示，鹿影科技成立于' -> '1月至'"", ""Changed: '9' -> '3'"", ""Changed: '\n2' -> '期间，作为一名大专文化的网络文学作者，利用 AI 程序撰写色情小说，并通过在境外黄色网站上发布，同时在其他网站进行销售。在短短五个月的时间内，柯某发布了数十篇色情小说，非法获利超过两万元。检方送检的\n3'"", ""Added: 'AI助力房地产市场'"", ""Changed: '讯' -> '飞，预计2030年规模将达1803.45亿美'"", ""Changed: '宝' -> '\n全球人工智能（AI）在房地产市场的应用正在迅速崛起，预计到2030年将达到1803.45亿美元，年均增长率高达35%。这一市场的快速发展得益于机器学习、预测分析等技术的进步，以及房地产管理对自动化的日益需求。在这一市场中，主要参'"", ""Changed: '腾讯' -> '者包括 Zillow 集团、Compass、Redfin 公司和 Reonomy 等。它们正在利用 AI 驱动的工具，提升客户体验，并优化物业管理流程。图源备注：图片由AI生成，图片授权服务商Midjourney美国市场是该领域的佼佼者，因其 AI 技术的快速采纳和健全的房地产基础设施。近期，\n4 小时前\n.\nAIbase\nOpenAI Chat Playground升级为Prompts Playground 更好测试、迭代提示词\nOpenAI 宣布，其广受欢迎的 Chat Playground 正式升级并更名为 Prompts Playground。这一更新带来了全新的设计和功能，旨在为用户提供更强大的工具，以便更好地测试、比较和迭代提示（prompts）。根据 OpenAI 在 X 平台上的最新介绍，此次重新设计整合了包括 Web 搜索和'"", ""Changed: '档打通' -> '件搜索在内的高级工具，进一步提升了用户体验和创作灵活性。据 OpenAI 开发团队透露，Prompts Playground 的核心目标是让用户能够更高效地探索和优化 AI 模型的交互方式。除了保留原有的对话功能外，新平台还允许用户保存和共享特定\n4 小时前\n.\nAIbase\nSesame发布CSM模型'"", ""Changed: '支持一键上传和导出为腾讯文档' -> '实时情感定制 AI语音合成迈向新高度'"", ""Changed: '腾讯' -> 'Sesame公司推出其最新语音合成模型CSM，引发业界关注。据官方介绍，CSM采用端到端基于Transformer的多模态学习架构，能够理解上下文信息，生成自然且富有情感的语音，声音效果贴近真人，令人惊艳。该模型支持实时语音生成，可处理文本和音频输入，用户还能通过调整参数控制语气、语调、节奏及情感等特性，展现高度灵活性。CSM被认为是AI语音技术的重要突破。其语音自然度极高，甚至“无法分辨是人工合成还是真人”。有用户录制视频展示CSM几近无延迟的表现，称其为“体验\n4 小时前\n.\nAIbase\nAnthropic、IBM 和 Meta 的技术领导者警告称，人工智能将取代软件开发人员的工作\n在最近一次国际会议上，Anthropic 首席执行官达里奥・阿莫迪（Dario Amodei）发表了一个引人注目的预测，他认为人工智能将在未来三到六个月内承担90% 的代码编写工作。阿莫迪表示，如果这一趋势持续下去，到了12个月后，AI 可能将几乎完全取代人类程序员的工作。他指出，尽管程序员仍需为 AI 设定特定的条件和目标，但未来这一过程也可能被技术所取代。阿莫迪认为，尽管人工智能将逐渐取代人类的某些工作，但这也将促使我们重新审视人力资源的有效利用。他指出，当前的思维模式已\n5 小时前\n.\nAIbase\n巨人网络发布行业首个DeepSeek原生游戏玩法 太空杀推出内鬼挑战\n巨人网络'"", ""Changed: '智' -> '社交推理游戏《太空杀》正式接入DeepSeek大模型，并推出基于该技术的原生游戏玩法“内鬼挑战”，目前该玩法已开启灰度测试，后续将面向全量用户开放。这标志着业内首次将DeepSeek大模型'"", ""Changed: '助手腾讯元宝与腾讯文档实现' -> '力'"", ""Changed: '打通，这一升级为' -> '应'"", ""Changed: '户带来了更加便捷高效的办公' -> '于游戏玩法创新，以AI驱动游戏核心玩法，重塑游戏的竞技和交互'"", ""Changed: '，有望改变现有的办公协作模式。在以往的工作场景中，用户需要在文档编辑与智能助手之间频繁进行复制粘贴操作，流程繁琐且易出错。而此次腾讯元宝的升级，成功解决了这一痛点。上传指引:移动端点击右下角“+”后选择腾讯文档;Web端点击“上传文档-上传腾讯文档”;现在，用户不仅可以从元宝一键上传腾讯文档，支持表格、文档、PPT、PDF、思维导图等多种格式，无需\n2 小时前\n.\nAIbase\nLuma开源图像模型预训练技术IMM 采样效率提高10倍\n人工智能初创公司Luma近日在X平台宣布，其开源了一项名为Inductive Moment Matching（IMM）的图像模型预训练技术。这一突破性技术以其高效和稳定的特性引发了广泛关注，被认为是生成式AI领域的一次重要进步。据X用户linqi_zhou透露，IMM是一种全新的生成范式，能够以单模型和单一目标从零开始稳定训练，同时在采样效率和样本质量上超越传统方法。他在帖子中兴奋地表示:“IMM在ImageNet256×256上仅用8步就达到了1.99FID（Fréchet Inception Distance），在CIFAR-10上仅用2步就达到了1.98FID。”这一性能不仅刷' -> '。'""]"

 注意，有些内容的可能仅仅是时间或者数据的变化，这样的内容更新是不需要总结的，可以看作没有更新，返回空数组

 要求：
 1. 提供简洁的内容更新概要
 2. 提取关键点
 3. 计算内容的列表长度
 返回结果使用中文,如果内容更新或者没有关键点，请返回空数组。
 请根据以上要求，总结出订阅内容的更新情况，并返回结果。


 返回格式json（请严格按照以下格式返回）：
 {{
 "summary": {{
 "content": [],
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 }},
 }}


 """

这个感觉也没什么问题，qwq-32b 的效果更好。

复盘

对照两版提示词，实质是三处改动：

范围从"时间的变化"扩成"时间或者数据的变化"——Changed: '1' -> '2' 这种裸数字变化终于被覆盖；
删掉了举例——现在回看，那两个时间变化的例子反而把模型的理解锚死在字面上的时间字符串，裸数字就漏了出去；
把"返回空数组"这个动作直接缀在"可以看作没有更新"后面——判断和行为写在同一句里，不靠模型自己把两段话联系起来。

验证也是从这次开始分两步走：先用构造的最小样例确认"该空的时候空不空"，再用真实数据回归"该有的时候有没有"。只测前者，会漏掉把真实更新也判成"没有更新"的过头修正。

三、超长文本：按变更单元分块，map-reduce 汇总

进入四月，新的问题来了：真实抓取的 diff 越来越长，一次全塞给模型开始顶不住 token 上限。这一节的完整可执行脚本放在本文同目录：解决上下文过长.py，下面讲思路，代码有删节（去掉了日志行），完整版直接看文件。

模型换成 Dashscope 上的 qwen-plus，走 OpenAI 兼容端点：

pip install langchain-core langchain-openai pydantic openai
export DASHSCOPE_API_KEY="你的密钥"

输出结构：从手写 dict 到 Pydantic

第一版的手写 SUMMARY_TEMPLATE 升级成了 Pydantic 模型，多了 url_list（每个关键点对应的 URL 二维数组）和 raw_response（LLM 原始响应存档）两个字段：

from pydantic import BaseModel, Field
from typing import List, Optional

class SummaryResponse(BaseModel):
 content: List[str] = Field(default_factory=list, description="内容更新摘要")
 key_points: List[str] = Field(default_factory=list, description="关键点列表")
 url_list: List[List[str]] = Field(default_factory=list, description="每个关键点对应的URL列表")
 word_count: int = Field(default=0, description="内容的总字数")
 generated_at: str = Field(default="", description="生成时间戳")
 status: str = Field(default="success", description="处理状态")
 error_message: Optional[str] = Field(default=None, description="错误信息（如有）")
 raw_response: Optional[str] = Field(default=None, description="LLM原始响应")

解析器换成 PydanticOutputParser：结构、类型、默认值都在一处定义，get_format_instructions() 直接生成 JSON 格式说明，用 partial_variables 注进提示词——不用再手抄一遍"请严格按照以下格式返回"的模板：

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import PydanticOutputParser
from langchain_openai import ChatOpenAI

self.llm = ChatOpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 model="qwen-plus",
)
self.parser = PydanticOutputParser(pydantic_object=SummaryResponse)
self.prompt_template = PromptTemplate(
 input_variables=["contentdiff"],
 partial_variables={"format_instructions": self.parser.get_format_instructions()},
 template="""
 You are a subscription content expert. Summarize the following content differences:

 {contentdiff}

 ### Notes:
 - Ignore updates that are only time or data changes (return empty arrays).
 - Ensure content and key_points lists have a one-to-one correspondence.
 - url_list is a 2D array, each sublist contains URLs for the corresponding key point.

 ### Requirements:
 1. Provide content update summaries (content) as an array.
 2. Extract key points (key_points) for each content item.
 3. Extract URLs for each key point (url_list); return empty arrays if none.
 4. Calculate word count for content (Chinese/English characters only, no punctuation/spaces).
 5. Return results in Chinese if updates exist; otherwise, return empty arrays.
 6. Follow this JSON format:

 {format_instructions}
 """
)

提示词本身换成了英文，但 Notes 第一条就是第二节踩坑换来的那句——Ignore updates that are only time or data changes。几轮迭代下来的结论，直接固化进了代码。

主流程：token 估算与分块决策

def generate_summary(self, contentdiff: str) -> SummaryResponse:
 avg_token_per_char = 0.5
 estimated_tokens = len(contentdiff) * avg_token_per_char
 if estimated_tokens > self.max_token_limit:
 return self.generate_summary_with_memory(contentdiff) # 超限走分块路径
 # 未超限：直接一条链处理

token 数不引 tokenizer，拿字符数乘 0.5 粗估。这个数不需要准——它只服务"要不要分块"这一个二元决策。宁可把 max_token_limit 设得比模型实际上限低一截，让估算误差只往"多分一块"的方向错，而不是该分没分、请求直接撞上下文上限。

分块策略：优先变更单元，字符数兜底

contentdiff 的结构天然适合按语义边界切：每条变更都是一个 ""Changed: ..."" / ""Added: ..."" / ""Deleted: ..."" 单元。固定字符切分会把一条变更从中间切断，半截单元对模型是纯噪音，还容易诱导出半句幻觉。所以正则优先按变更单元攒包，实在匹配不到单元（比如输入根本不是 diff 格式）才按字符数硬切兜底：

def chunking_content(self, contentdiff: str) -> List[str]:
 avg_token_per_char = 0.5
 if len(contentdiff) * avg_token_per_char <= self.max_token_limit:
 return [contentdiff]

 chunks = []
 change_units = re.findall(r'""(?:Changed|Added|Deleted):.*?"",', contentdiff, re.DOTALL)

 if not change_units:
 # 兜底：没有变更单元，按字符数硬切
 chars_per_chunk = int(self.max_token_limit / avg_token_per_char)
 for i in range(0, len(contentdiff), chars_per_chunk):
 chunks.append(contentdiff[i:i + chars_per_chunk])
 else:
 # 优先：按变更单元攒包
 chars_per_chunk = int(self.max_token_limit / avg_token_per_char)
 current_chunk = ""
 for unit in change_units:
 if len(current_chunk) + len(unit) > chars_per_chunk:
 chunks.append(current_chunk)
 current_chunk = unit
 else:
 if current_chunk:
 current_chunk += "\n"
 current_chunk += unit
 if current_chunk:
 chunks.append(current_chunk)
 return chunks

map：逐块抽取

每个块用一个简单的 chunk_prompt 抽 content / key_points / urls，三个 collected 列表各自累积。单块失败只跳过该块，不炸全局：

for i, chunk in enumerate(content_chunks):
 chunk_prompt = PromptTemplate(
 input_variables=["chunk_content"],
 template="""
 Analyze the following content difference chunk:

 {chunk_content}

 Provide in JSON format:
 1. content: List of content update summaries
 2. key_points: List of corresponding key points
 3. urls: List of URLs (2D array)

 Return only JSON, no extra text.
 """
 )
 chunk_chain = chunk_prompt | self.llm
 try:
 chunk_result = chunk_chain.invoke({"chunk_content": chunk})
 chunk_content = chunk_result.content if hasattr(chunk_result, 'content') else str(chunk_result)
 json_match = re.search(r'\{.*\}', chunk_content, re.DOTALL)
 if json_match:
 chunk_json = json.loads(json_match.group(0))
 if 'content' in chunk_json and isinstance(chunk_json['content'], list):
 collected_content.extend(chunk_json['content'])
 if 'key_points' in chunk_json and isinstance(chunk_json['key_points'], list):
 collected_key_points.extend(chunk_json['key_points'])
 if 'urls' in chunk_json and isinstance(chunk_json['urls'], list):
 collected_urls.extend(chunk_json['urls'])
 memory.save_context(
 {"input": f"Chunk {i+1}:\n{chunk[:200]}..."},
 {"output": f"Analysis:\n{chunk_content[:200]}..."},
 )
 except Exception as e:
 continue # 单块失败只跳过，不炸全局

reduce：汇总成最终结果

所有块处理完，把三个 collected 列表交给 final prompt，让模型合并、去重，生成最终的 SummaryResponse：

final_prompt_template = PromptTemplate(
 input_variables=["collected_content", "collected_key_points", "collected_urls", "format_instructions"],
 template="""
 Generate a final summary from the collected information:

 Content updates: {collected_content}
 Key points: {collected_key_points}
 URLs: {collected_urls}

 Return JSON in this format:

 {format_instructions}

 Notes:
 1. Ensure content and key_points correspond one-to-one.
 2. url_list is a 2D array for each key point's URLs.
 3. Calculate word_count (characters, no punctuation/spaces).
 4. Merge or remove duplicate content.
 5. Return only JSON.
 """
)
final_chain = final_prompt_template | self.llm
raw_response = final_chain.invoke({
 "collected_content": collected_content,
 "collected_key_points": collected_key_points,
 "collected_urls": collected_urls,
 "format_instructions": self.parser.get_format_instructions(),
})

解析成功后还有一层本地兜底——能本地算的字段不依赖模型：

response = self.parser.parse(self.extract_json(raw_content))

if not response.generated_at:
 response.generated_at = datetime.now().isoformat() # 时间戳本地填，不信模型
if response.word_count == 0 and response.content:
 response.word_count = len("".join(response.content).replace(" ", "").replace(",", "").replace(".", ""))
if len(response.url_list) < len(response.key_points):
 for _ in range(len(response.key_points) - len(response.url_list)):
 response.url_list.append([]) # 补齐一一对应
response.raw_response = raw_content # 永远存原文，排查不用重跑

容错与重试

模型偶尔会在 JSON 前后裹话（“以下是总结：…“之类），裸 json.loads 直接炸。extract_json 用一个贪婪的 \{.*\}（DOTALL）把最外层花括号之间的内容抠出来再交给解析器：

def extract_json(self, raw_content: str) -> str:
 json_match = re.search(r'\{.*\}', raw_content, re.DOTALL)
 return json_match.group(0) if json_match else raw_content

重试是外层 while 循环，直接路径和最终汇总两条路径各挂一个，间隔 retry_delay 秒。所有重试耗尽也不抛异常——返回一个 status="error" 的 SummaryResponse，下游拿到的永远是合法结构，错误本身也是数据：

retries = 0
while retries < self.max_retries:
 try:
 raw_response = chain.invoke({"contentdiff": contentdiff})
 response = self.parser.parse(self.extract_json(raw_response.content))
 ...
 return response
 except Exception as e:
 retries += 1
 if retries < self.max_retries:
 time.sleep(self.retry_delay)
# 重试耗尽：返回带错误信息的合法结构
return SummaryResponse(status="error", error_message=f"Failed to parse SummaryResponse: {e}", ...)

演示的时候把 max_token_limit 调到 300 就能强制走分块路径，不用真造一份 3 万 token 的输入。

如实交代：memory 并没有真正生效

原文的标题把这部分叫"记忆机制处理超长文本”，但合并这篇的时候要如实交代两件事：

__init__ 里初始化的 self.memory，在当前实现里从未被 generate_summary 真正使用——真正干活的是 generate_summary_with_memory 里局部新建的另一个实例。
局部 memory 也只做了 save_context——把每块输入/输出的前 200 个字符存进去，理论上为后续块提供上下文。但实际每个块的处理是相对独立的：把结果串起来的是代码里的三个 collected 列表，最终汇总读的也是它们，不是 memory。

所以这套流程的本质就是 map-reduce：map 是逐块抽取，reduce 是最终汇总。要复现的话，把 memory 相关代码整个删掉，主流程不受影响。

⚠️ 版本注记：ConversationSummaryBufferMemory 来自 langchain.memory，属于 legacy memory 体系，LangChain 1.0 已将其整体移除。现在的等价做法是 LangGraph 的 checkpointer（线程级持久化）或对消息列表做裁剪/摘要。这里保留原样，是为了如实记录当时的选择。

四、工程细节清单

把散在代码里的取舍集中列一遍：

细节	做法	取舍
重试	直接路径与汇总路径各挂一个外层 while 循环 + `time.sleep(retry_delay)`	直观、间隔和日志可控；LCEL 的 `.with_retry(stop_after_attempt=3)` 一行可替换，脚本里实际落地的是循环写法
JSON 容错	`extract_json` 正则 `\{.*\}`（DOTALL）先抠 → `PydanticOutputParser.parse` 再校验	模型在 JSON 前后裹话时不至于炸；`raw_response` 永远存原文，排查不用重跑
token 估算	`len(contentdiff) * 0.5`	不引 tokenizer、零依赖；只服务"分不分块"的二元决策，把 `max_token_limit` 设保守点吸收误差
失败语义	重试耗尽不抛异常，返回 `status="error"` 的 `SummaryResponse`	下游拿到的永远是合法结构，错误也是数据

几个不起眼的小处理，一并记在这里：

generated_at 不信模型，本地 datetime.now().isoformat() 填；
word_count 为 0 且有 content 时本地重算（直接路径：拼接后去空格去逗号句号数长度）；
url_list 比 key_points 短就补空列表，保住一一对应；
每块抽取失败 continue 跳过，一块的失败不拖垮整份摘要。

还有一处坑，合并本文时验证过：脚本里 memory 路径的字数兜底写的是 re.sub(r'[\s\p{P}]', '', content_text, flags=re.UNICODE)——\p{P} 是 PCRE / regex 第三方库的语法，标准库 re 不认，这行会直接抛 re.error: bad escape \p（外层 try 会接住，触发无意义的重试）。要按原意去标点，得换 regex 库或手写标点集。直接路径的同名逻辑用的是 replace(" ", "").replace(",", "").replace(".", "")，土，但不会炸。

总结

这个项目从第一版管线到能吃下超长 diff，前后一个月，值得留下的结论就这几条：

提示词是 agent 的行为规格，不是写给人的备忘。 对人类差不多的提示词，对 agent 是天壤之别——“时间或者数据的变化"几个字的改动就是质变。改完之后，最小样例和真实数据各验证一轮，缺一不可。
长文本的正解是 map-reduce 分块。 按语义边界（变更单元）切块优先、字符数兜底，逐块抽取再汇总，朴素但有效；引入的"记忆机制"实际没起作用，如实记录比包装成"记忆驱动"更有参考价值。
结构化输出的可靠性靠工程兜底，不靠模型自觉。 容错解析、重试、永不抛异常的失败语义、raw_response 存档——这一层做好了，模型偶尔不听话只是重试一次的事。
模型选型：这个任务上 qwq-32b 比 grok3 表现更好。 样本很小，是个人判断，但它是双模型、双轮验证之后得出的。

溯源

本文整合自同一个项目的三篇旧文，按时间顺序：

《使用 LangChain 构建订阅内容更新总结智能代理》（2025-03-13）——并入本文第一节：第一版管线、SubscriptionAgent 逐段讲解、LLM 输出不一致的对策。
《提示词使用教程|工程应用实践》（2025-03-14）——并入本文第二节：误判问题、提示词改动前后对照、双模型验证截图与个人结论。
《08-内容分块 (chunking) 和记忆机制 (memory) 处理超出 LLM Token 限制的长文本》（2025-04-12）——并入本文第三节：分块策略、容错重试、可执行脚本解决上下文过长.py。

合并时做的处理，都列在这里：

原文一的 from langchain_core.retry import retry 是不存在的 API（当时的记录里混进了幻觉写法），合并版替换为 .with_retry() 与外层重试循环两种真实写法；get_ali_llm 是项目内模块，补了 ChatOpenAI + base_url 的等价写法。
原文三标题里的"记忆机制"如第三节坦白并未真正生效，合并版按实际代码路径写成 map-reduce 分块，并补了 legacy memory 的版本注记。
原文里被 Markdown 链接污染的 URL（base_url="[https://...](...)" 形式）已还原为纯 URL。
原文二的通用技巧小节（少样本提示等）与烂尾的"PUA大模型"小节没有并入正文；后者保存的 Windsurf（Codeium）系统提示词泄漏截图仍保留在 images/index/windsurf-system-prompt.png。

DeepAgents完全指南

Tue, 08 Sep 2026 11:26:34 +0800

DeepAgents 完全指南

本文基于 deepagents==0.7.15（Python，2026-09-16 发布）撰写，涵盖从入门概念到生产部署的全部核心内容。0.x 版本 API 变动较快，如果你的版本低于 0.6，请先升级再对照本文——0.6.0 改了消息历史的持久化格式，升级路径见 3.5 节。

第一章：DeepAgents 是什么

1.1 一句话定义

DeepAgents（包名 deepagents）是 LangChain 团队推出的一个 agent harness（智能体运行框架）—— 一个开箱即用、高度可定制、面向长周期多步任务的智能体运行时。

它不是又一个 LangGraph 图编排工具，也不只是 LangChain 的薄封装，而是一个带有以下"观点"（opinionated）的完整框架：

默认就适合长任务：内置文件系统、上下文压缩、子智能体委派，不用你自己搭。
每个组件都可以替换：模型、文件后端、中间件、子智能体、技能，全部可插拔。
模型无关：只要模型支持 tool calling 就能用——GPT、Claude、Gemini、Qwen、本地 Ollama 都行。
生产就绪：底层是 LangGraph，天然支持流式输出、持久化、checkpoint、断点恢复。

灵感来源是 Claude Code：团队想搞清楚 Claude Code 为什么通用，然后把那些设计提炼成一个可编程的框架。

1.2 在 LangChain 生态中的位置

理解 DeepAgents 的关键，是理解 LangChain 生态的三层结构：

┌─────────────────────────────────┐
│ LangSmith │ ← 可观测性、评测、监控
├─────────────────────────────────┤
│ Deep Agents │ ← 完整 harness（本文主角）
├─────────────────────────────────┤
│ LangChain create_agent │ ← 轻量 agent（无内置文件系统/子agent）
├─────────────────────────────────┤
│ LangGraph │ ← 图运行时（状态、节点、边）
└─────────────────────────────────┘

LangGraph 是底层的图运行时，管状态、节点、边、checkpoint。
LangChain create_agent 是最小的 agent 循环：模型 + 工具 + 消息 → 循环 → 回复。
DeepAgents 在 create_agent 之上叠加了一整套 middleware（文件系统、子智能体、上下文压缩、技能、权限），把"裸 agent"变成一个完整的 agent harness。
任何 LangGraph 编译后的图都可以作为 DeepAgents 的子智能体传入，实现自定义编排与 DeepAgents 默认行为的混合。

什么时候用什么层：

场景	用什么
需要 planning、context 管理、子智能体委派	DeepAgents
只需要一个简单 tool-calling 循环	LangChain `create_agent`
agent 循环不是你想要的形状，需要自定义图	LangGraph
需要监控、评估、trace	LangSmith（可与上面任何层搭配）

1.3 核心能力一览

能力	说明
文件系统	内置 `ls / read_file / write_file / edit_file / delete / glob / grep`，支持多种可插拔后端
子智能体	主 agent 通过 `task` 工具委派任务给拥有独立上下文的子 agent
上下文管理	自动摘要长对话，超大工具输出自动转存到文件系统
Shell 执行	通过 Sandbox 后端提供 `execute` 工具
代码执行	`CodeInterpreterMiddleware`（实验性）在受限 QuickJS 沙箱里跑代码与编程式工具调用
持久记忆	可插拔的状态和存储后端，支持跨会话记忆
Human-in-the-Loop	工具调用或文件操作前暂停，等待人工审批/编辑/拒绝
Skills	可复用的行为模板，按需加载，渐进式披露
结构化输出	主 agent 和子 agent 均支持 Pydantic 模型作为输出 schema
MCP 工具	可接入任意 MCP server 作为工具

1.4 安装

# 推荐
uv add deepagents

# 或者
pip install deepagents

要求 Python >= 3.11, < 4.0。

第二章：架构与中间件协议

DeepAgents 的一切能力都由**中间件栈（middleware stack）**提供。理解这个栈，就理解了 DeepAgents 的全部。

2.1 中间件栈的完整顺序

当你调用 create_deep_agent() 时，框架会按以下顺序组装中间件：

┌─ 基础栈（Base stack）────────────────────────────────┐
│ 1. SkillsMiddleware （仅当传入 skills） │
│ 2. FilesystemMiddleware （始终存在） │
│ 3. SubAgentMiddleware （有子智能体时存在） │
│ 4. SummarizationMiddleware （始终存在） │
│ 5. PatchToolCallsMiddleware （始终存在） │
│ 6. AsyncSubAgentMiddleware （有异步子智能体时存在） │
│ 7. 你的自定义 middleware （插入到这里） │
├─ 尾部栈（Tail stack）────────────────────────────────┤
│ 8. Harness profile 额外中间件 │
│ 9. 工具排除过滤（excluded_tools） │
│ 10. AnthropicPromptCachingMiddleware（非 Anthropic noop）│
│ 11. BedrockPromptCachingMiddleware（未装则跳过） │
│ 12. FireworksPromptCachingMiddleware（未装则跳过） │
│ 13. MemoryMiddleware （仅当传入 memory） │
│ 14. HumanInTheLoopMiddleware （仅当传入 interrupt_on） │
└──────────────────────────────────────────────────────┘

关键点：

你的 middleware 插在位置 7，在核心中间件之后、prompt caching 和 memory 之前。
如果你的 middleware 实例的 .name 与某个内置中间件相同，它会原地替换该内置实例，而不是追加。
某些核心中间件（FilesystemMiddleware、SubAgentMiddleware、PatchToolCallsMiddleware）受框架保护，不能通过 excluded_middleware 移除。
上图是默认组装结果。实验性中间件（如 CodeInterpreterMiddleware）不在其中，只有你显式加进 middleware 才会出现。

2.2 核心中间件详解

FilesystemMiddleware

始终存在。提供以下工具：

工具	功能
`ls(path)`	列出目录内容
`read_file(file_path, offset, limit)`	读取文件，支持分页和多模态（图片/音频/视频）
`write_file(file_path, content)`	写入文件，已存在的文件直接覆盖（0.7.0 起的行为，此前是报错）
`edit_file(file_path, old_string, new_string, replace_all)`	精确字符串替换，`old_string` 为空会被拒绝（0.7.14 起）
`delete(file_path)`	删除文件或递归删除目录（0.7.0 新增）
`glob(pattern, path)`	模式匹配查找文件
`grep(pattern, path, glob)`	文本搜索（优先使用 ripgrep）
`execute(command, timeout)`	执行 shell 命令（仅当后端实现 SandboxBackendProtocol）

0.7.0 开始，这套读写工具明显向「弱模型也能稳定用」的方向调过一遍，几个行为值得记住：

write_file 覆盖而不报错。以前写同名文件会失败，agent 得先 delete 再写；现在直接覆盖。
read_file 分页可续读。返回结果里会报总行数、剩余行数以及下一次该用的 offset，模型不用自己猜还剩多少没读。
grep / glob 返回部分结果而不是卡死。在大目录树上超过上限时，结果里带一个 truncated 标记，grep 另有 1000 条匹配上限，并支持流式输出和可选的上下文行。
edit_file 拒绝空的 old_string。以前传空串会导致不可预期的替换（0.7.14 修的）。

如果你只想暴露其中一部分工具（比如给 agent 一个只读的文件视图），FilesystemMiddleware 接受工具白名单：

from deepagents.middleware.filesystem import FilesystemMiddleware

fs_mw = FilesystemMiddleware(tools=["ls", "read_file", "glob", "grep"])

agent = create_deep_agent(model=model, middleware=[fs_mw])

它还负责大工具结果的自动转存：

默认 20000 token 以上的工具输出会被转存到文件系统（路径如 /large_tool_results/），上下文中只保留摘要和文件路径。
用户消息超过 50000 token 也会被转存。
转存文件按 tool_call_id 命名；对于没有 ID 的调用，0.7.15 起会生成唯一路径，避免多次转存撞到同一个文件名。

SubAgentMiddleware

有子智能体时存在。提供 task 工具，主 agent 用它委派任务给子 agent。子 agent 拥有完全隔离的上下文窗口——主 agent 只看到子 agent 的最终输出。

SummarizationMiddleware

始终存在。当对话 token 数超过阈值时，自动将旧消息压缩为摘要，完整历史转存到文件系统（路径如 /conversation_history/）。阈值的默认值会根据模型的最大输入 token 自动计算，回退方案是固定保留最近 20 条消息。

PatchToolCallsMiddleware

始终存在。修复消息历史中悬空的工具调用（例如 agent 在中断后恢复、或收到格式错误的 tool-call 参数时），确保消息流的一致性。

SkillsMiddleware

仅当传入 skills 参数时存在。将技能目录中的 SKILL.md 元数据（name + description）注入系统提示词，让 agent 知道有哪些技能可用。Agent 判断当前任务匹配某个技能时，会主动读取该技能的完整指令。

MemoryMiddleware

仅当传入 memory 参数时存在。在 agent 启动时加载指定的 AGENTS.md 文件内容，追加到系统提示词中。这是 DeepAgents 的"启动记忆"机制。

CodeInterpreterMiddleware（Interpreter，beta）

0.6.0 引入，不在默认栈里，需要你显式加进 middleware。官方文档里这块叫 Interpreters——给 agent 一个进程内的可编程工作区：agent 写一段 JavaScript，运行时执行后只把结果返回，中间变量不进入模型上下文。

它解决的是一个很具体的问题：正常的工具调用循环里，一次模型 turn 发出的那批 tool call 是固定的——不能循环、不能根据结果分支、不能重试、也不能把上一个调用的输出喂给下一个，除非再来一轮模型推理，而且每个结果都会回到上下文里。让模型去分派几百个条目本身也不可靠，它往往只抽样一部分。Interpreter 把这类编排从"模型逐步决策"挪到"代码里跑"，模型只需要想清楚要做什么。

pip install -U "deepagents[quickjs]"

from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
 model=model,
 middleware=[CodeInterpreterMiddleware()],
)

它给 agent 加了一个 eval 工具，agent 写 JS 调它，你不用手动调。几个要点：

默认零外部能力。QuickJS 环境下拿不到宿主机文件系统、网络、shell、包管理器，连时钟都没有，只能计算、保状态、往 console.log/warn/error 写。要放开只有两条明确的口子：PTC（programmatic tool calling，用 ptc=["web_search"] 给一个工具白名单，代码里通过 tools.webSearch(...) 调）和动态子智能体（有子智能体时自动暴露 task() 全局，可以 Promise.all 并行分派）。
状态持久化由 mode 控制："thread"（默认，跨 turn 持久，每轮结束写快照）、"turn"（仅一轮内保持）、"call"（每次 eval 全新 REPL）。快照只保留可序列化的数据——函数和类恢复后会变成不可访问的残留物。
隔离是"能力受限"而不是"内存隔离"。QuickJS 跑在同进程里，官方明确说这是 scoped interpreter runtime，不是生产级 sandbox。不可信代码要另外放到独立进程或容器里跑。
PTC 不经过常规工具调用路径，所以 interrupt_on 的审批对 PTC 里调用的工具不生效。PTC 白名单本身就是权限边界，别把能碰敏感系统、花钱或改数据的工具放进去。

和 SandboxBackend 的 execute 分工很清楚：sandbox 是"对着环境写代码"（shell、装依赖、跑测试、改文件），interpreter 是"在 agent 循环里写代码"（组合工具、保状态、决定什么回给模型）。

HumanInTheLoopMiddleware

仅当传入 interrupt_on 或 permissions 中有 mode="interrupt" 的规则时存在。在指定的工具调用前暂停执行，返回中断信息，等待人工决策（approve / edit / reject / respond）。

2.3 系统提示词的组装

最终发给模型的 system prompt 不是一个字符串拼两个变量那么简单。完整顺序是：

1. 你传入的 system_prompt （可选的用户层）
2. 基础 agent 提示词 （BASE）
3. Memory 提示词 （仅当传了 memory：AGENTS.md + 使用说明）
4. Skills 提示词 （仅当传了 skills：技能位置 + 各技能 frontmatter + 用法）
5. 虚拟文件系统提示词 （含 execute 工具说明，如果用 sandbox 后端）
6. 子智能体提示词 （task 工具的用法）
7. 你自定义中间件附带的提示词 （如果自定义中间件有）
8. Human-in-the-loop 提示词 （仅当设置了 interrupt_on）

HarnessProfile 则控制其中的 BASE 和 SUFFIX 两个变量：

base_system_prompt：整体替换基础提示词。
system_prompt_suffix：在末尾追加指令。

大部分时候你只需要关心 system_prompt 参数。BASE 和 SUFFIX 是框架层面为不同模型提供的默认调优，一般不需要动。

注意 system_prompt 是静态的——每次调用都一样。如果你需要动态提示词（比如按用户权限切换「你有管理员权限」和「你只读」，或者从长期记忆里注入用户偏好），要用 @dynamic_prompt 写中间件，在里读 request.runtime.context 和 request.runtime.store。只在工具内部用到 context 时不必写中间件——工具本身就能拿到 ToolRuntime。

值得一提的是 0.7.0 对这块做过一次大幅瘦身，动机是"别把工具的用法重复写两遍"——工具 schema 本身已经说明了怎么用，再往提示词里塞一遍纯属浪费 token。具体做法是：内置的 BASE 提示词默认改为空，同时删掉与工具 schema 重复的说明性文字。效果是默认 agent 的工具描述 token 从 4005 降到 2302（−43%）；再叠上空 BASE 和按需开启的 todos，单轮输入的 token 从 5395 降到 1895（−65%）。工具的实际行为没有变化。

如果你在自己的 system_prompt 里也习惯把工具用法写得很细，这一点可以直接借鉴：先看 schema 已经说了什么，再决定提示词里还欠什么。

2.4 HarnessProfile

HarnessProfile 是"每个模型的默认调优配置包"。当你传入一个模型时，框架会自动解析对应的 profile，决定：

额外的中间件（如 Anthropic prompt caching、Bedrock prompt caching）
是否禁用某些内置工具（excluded_tools）
是否排除某些中间件（excluded_middleware）
额外的系统提示词内容

大部分使用场景不需要手动创建 profile。框架会根据模型类型自动选择。

内置 profile 的覆盖范围一直在扩。0.7.0 加入了 NVIDIA Nemotron 3 Ultra 的 profile，同时带上了 NIM 的 app-origin 归因；prompt caching 这一侧也补齐了 Bedrock（走 deepagents[aws] extra）和 Fireworks（自动做缓存会话亲和）。0.7.15 顺手修了两个 profile 相关的小问题：model profile 的 key 现在允许出现冒号，Nemotron 的内置 profile 也要求真正的 task transition 才生效。

第三章：`create_deep_agent` 完整签名

这是 DeepAgents 最核心的函数，理解了每个参数，就理解了整个框架的入口。

from deepagents import create_deep_agent

agent = create_deep_agent(
 model=..., # 模型
 tools=..., # 自定义工具
 system_prompt=..., # 系统提示词
 middleware=..., # 额外中间件
 subagents=..., # 子智能体配置
 skills=..., # 技能目录路径
 memory=..., # AGENTS.md 记忆文件路径
 permissions=..., # 文件系统权限规则
 backend=..., # 文件系统后端
 interrupt_on=..., # 人工审批的工具名映射
 response_format=..., # 结构化输出 schema
 state_schema=..., # 自定义图状态 schema
 context_schema=..., # 运行时上下文 schema
 checkpointer=..., # LangGraph checkpointer（持久化）
 store=..., # LangGraph store（跨会话存储）
 debug=..., # 调试模式
 name=..., # 图的名称
 cache=..., # 缓存
)

3.1 `model` 参数

接受三种形式：

# 1. 字符串（推荐——使用 provider:model 格式）
agent = create_deep_agent(model="openai:gpt-5.5")

# 2. 预初始化的 LangChain ChatModel 实例
from langchain_openai import ChatOpenAI
model = ChatOpenAI(model="gpt-5.5", temperature=0)
agent = create_deep_agent(model=model)

# 3. 传入 None（已弃用，默认是 claude-sonnet-4-6）
# 从 0.5.3 开始弃用，将在 1.0.0 中移除

provider:model 字符串由 LangChain 的 init_chat_model 函数解析。支持的 provider 包括：openai, anthropic, google_genai, aws, azure_openai, ollama, fireworks, together, mistral, groq, xai 等。

重要：OpenAI 模型的 Responses API 默认行为

从 DeepAgents 0.6.x 开始，如果你使用 OpenAI 模型，默认走 Responses API（不是 Chat Completions）。这是因为 Responses API 支持 OpenAI 的内置工具（web search、code interpreter 等）。

如果你想强制走 Chat Completions：

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.5", use_responses_api=False)
agent = create_deep_agent(model=model)

如果你想用 Responses API 但禁用服务端数据保留：

model = init_chat_model(
 "openai:gpt-5.5",
 use_responses_api=True,
 store=False,
 include=["reasoning.encrypted_content"],
)
agent = create_deep_agent(model=model)

接入阿里云百炼（DashScope）

百炼提供 OpenAI 兼容端点，走 Chat Completions 协议：

from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent

model = ChatOpenAI(
 model="qwen-plus", # 或 qwen3-max、qwen-max 等
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

agent = create_deep_agent(model=model, tools=[my_tools])

如果需要百炼的 web_search 等服务端内置工具，有两种策略：

在 tools 中包装：把百炼 Responses API 的 web_search 调用封装为一个普通 function tool，DeepAgents 通过 tool calling 调用它。
直接用 Responses API：绕过 DeepAgents，直接调用百炼的 Responses API（失去 DeepAgents 的 harness 能力）。

3.2 `tools` 参数

传入模型可以调用的自定义工具。这些工具与内置工具合并（additive），不会替换内置工具：

from langchain.tools import tool

@tool
def search_database(query: str) -> str:
 """搜索产品数据库，返回匹配结果"""
 return db.search(query)

@tool
def generate_report(data: dict) -> str:
 """根据数据生成分析报告"""
 return report_gen.run(data)

agent = create_deep_agent(model=model, tools=[search_database, generate_report])

要移除内置工具，需要使用 HarnessProfile 的 excluded_tools 机制，而不是简单地不传。

3.3 `system_prompt` 参数

你自定义的系统提示词。可以是字符串或 SystemMessage：

agent = create_deep_agent(
 model=model,
 system_prompt="你是一个数据分析助手。在给出结论之前，先用 Python 工具验证数据。",
)

如果传入 SystemMessage，会保留其上的 cache_control 标记（用于 Anthropic prompt caching 的显式断点）。

3.4 `response_format` 参数

让 agent 的最终输出符合指定的结构化 schema：

from pydantic import BaseModel, Field

class ResearchReport(BaseModel):
 """研究报告的结构化输出"""
 title: str = Field(description="报告标题")
 summary: str = Field(description="核心发现摘要")
 key_findings: list[str] = Field(description="关键发现列表")
 confidence: float = Field(description="置信度 0-1")
 sources: list[str] = Field(description="参考来源")

agent = create_deep_agent(
 model=model,
 tools=[web_search],
 response_format=ResearchReport,
)

result = agent.invoke({"messages": [{"role": "user", "content": "调研 LangGraph 的最新特性"}]})

# 访问结构化输出
report = result["structured_response"]
print(report.title)
print(report.confidence)

response_format 接受：

Pydantic BaseModel 子类
Python dataclass
TypedDict
JSON Schema 字典
ToolStrategy(schema)：通过 tool calling 提取
ProviderStrategy(schema)：使用 provider 原生结构化输出
AutoStrategy(schema)：自动选择最佳策略

3.5 `checkpointer` 与持久化

DeepAgents 底层是 LangGraph，所以天然支持持久化：

from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
 model=model,
 tools=tools,
 checkpointer=MemorySaver(), # 内存持久化
)

# 使用 thread_id 区分不同会话
config = {"configurable": {"thread_id": "user-123-session-456"}}
result = agent.invoke({"messages": [...]}, config=config)

生产环境使用 PostgreSQL 或 SQLite：

from langgraph.checkpoint.postgres import PostgresSaver

checkpointer = PostgresSaver.from_conn_string("postgresql://...")
agent = create_deep_agent(model=model, checkpointer=checkpointer)

文件系统（StateBackend）的内容也会随 checkpoint 持久化——同一 thread 内跨多轮对话，文件不会丢失。

DeltaChannel：0.6.0 起的持久化格式变更

从 0.6.0 开始，消息历史和 agent 文件改用 DeltaChannel 存储。原来的做法是每一步都把累积后的全量值重新序列化进 checkpoint；DeltaChannel 只存这一步写入的增量。对长线程来说这是数量级的差别——checkpoint 的大小不再随对话变长而线性膨胀。相应地，可以配 snapshot_frequency=K 每 K 步写一次全量快照，用来给读取延迟封顶。

这里有一条必须知道的兼容性红线：一旦 thread 用 0.6.0+ 持久化过，就不支持回滚。

DeltaChannel 写出的 checkpoint 是新格式，0.6.0 之前的版本读不了。降级时这些 channel 会切回非 delta 实现，而已有的 delta checkpoint 就变成不可读了——症状是状态重建不完整或直接出错，而且不一定当场暴露。

真的需要降级，只有两条路：

先用 delta-channel-dump 恢复脚本把受影响的 thread 迁移掉；
或者直接丢弃这些 thread。

推广来说：不要让同一个 channel 在 delta 和非 delta 两种表示之间来回切换。升级前先想清楚要不要留退路，留退路就在升级前把 thread 导出。

第四章：文件系统与后端

DeepAgents 内置的文件系统是一个虚拟文件系统（VFS）。它不是直接操作你的操作系统文件，而是通过**后端协议（backend protocol）**抽象，让文件操作落到不同的存储介质上。

4.1 内置工具

工具名	签名	说明
`ls`	`ls(path: str) -> list[str]`	列出目录内容
`read_file`	`read_file(file_path: str, offset: int = 0, limit: int = 500) -> str`	读取文件内容，支持偏移和限制
`write_file`	`write_file(file_path: str, content: str) -> str`	写入文件，已存在则直接覆盖
`edit_file`	`edit_file(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> str`	精确字符串替换
`delete`	`delete(file_path: str) -> str`	删除文件（需要后端支持删除操作）
`glob`	`glob(pattern: str, path: str = "/") -> list[str]`	模式匹配查找
`grep`	`grep(pattern: str, path: str = "/", glob: str = None) -> list[str]`	内容搜索（优先使用 ripgrep）
`execute`	`execute(command: str, timeout: int = 300) -> str`	执行 shell 命令（仅当后端实现 SandboxBackendProtocol）

读类工具在 0.7.0 之后都改成了「宁可返回部分结果，也不要卡住」的语义，这是专门为开源模型调过的——弱模型容易在大目录树上触发一次巨量 grep，然后整轮就废了：

read_file 会告诉你总共多少行、还剩多少行，以及下一次该传的 offset，模型可以稳定地一页页往下读。
grep / glob 命中过多时返回带 truncated 标记的部分结果；grep 另有 1000 条匹配上限，支持流式输出和可选上下文行。
glob 在路径不合理时会主动提示该往哪个 path 下找（0.7.14 起）。
顺带一提，edit_file 从上到下按 old_string 精确匹配，传空串会被直接拒绝。

4.2 后端协议

DeepAgents 的文件后端遵循 BackendProtocol。核心方法是：

class BackendProtocol(Protocol):
 def ls(self, path: str) -> list[str]: ...
 def read(self, file_path: str, offset: int = None, limit: int = None) -> str: ...
 def write(self, file_path: str, content: str) -> None: ...
 def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> None: ...
 def delete(self, file_path: str) -> None: ...
 def glob(self, pattern: str, path: str = "/") -> list[str]: ...
 def grep(self, pattern: str, path: str = "/", glob: str = None) -> list[str]: ...

如果后端实现了 SandboxBackendProtocol（继承自 BackendProtocol，额外要求 execute 方法），就会额外暴露 execute 工具。

4.3 StateBackend（默认）

StateBackend 是默认后端。文件内容直接存储在 LangGraph 的 state 中：

# 不传 backend 参数，默认使用 StateBackend
agent = create_deep_agent(model=model, tools=tools)

# 文件存在 state["files"] 字典中，key 是路径，value 是内容字符串
result = agent.invoke({"messages": [{"role": "user", "content": "写一个 hello.py"}]})
print(result["files"]) # {"/hello.py": "print('hello world')"}

特点：

文件随 checkpoint 持久化，同一 thread 内跨会话不丢失。
跨 thread 不共享（每个 thread 有独立的 state）。
无需外部依赖。
适合快速原型和不需要真正落盘的场景。

4.4 CompositeBackend

CompositeBackend 允许你把不同路径前缀路由到不同后端，实现"混合存储"：

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend, SandboxBackend

backend = CompositeBackend(
 default=StateBackend(),
 routes={
 "/workspace": StateBackend(),
 "/artifacts": StoreBackend(store=my_store, namespace=("artifacts",)),
 "/memory": StoreBackend(store=my_store, namespace=("agent_memory",)),
 "/sandbox": SandboxBackend(root_dir="/tmp/agent_sandbox", timeout=60),
 "/data": CompositeBackend.FilesystemBackend(root_dir="/path/to/shared_data"),
 },
)

agent = create_deep_agent(model=model, backend=backend)

4.5 SandboxBackend

SandboxBackend 允许 agent 在一个受控的目录中执行 shell 命令：

from deepagents import create_deep_agent
from deepagents.backends import SandboxBackend

backend = SandboxBackend(
 root_dir="/tmp/agent_workspace",
 timeout=120, # 命令超时（秒）
 max_output_size=50000,
)

agent = create_deep_agent(model=model, backend=backend)

# agent 可以调用 execute("pip install requests") 或 execute("python analysis.py")

实现 SandboxBackendProtocol 后，execute 工具会自动暴露给 agent。

4.6 FilesystemBackend（本地真实文件系统）

如果你想让 agent 直接操作本地磁盘（例如代码编辑、数据处理），可以使用 FilesystemBackend：

from deepagents.backends.filesystem import FilesystemBackend

backend = FilesystemBackend(root_dir="/Users/zata/code/my-project")

agent = create_deep_agent(model=model, backend=backend)

# agent 可以 read_file / write_file / edit_file / glob / grep 操作真实文件

4.7 StoreBackend（跨会话存储）

StoreBackend 利用 LangGraph 的 Store 接口，将文件内容存储在一个跨 thread 共享的键值存储中：

from langgraph.store.memory import InMemoryStore
from deepagents.backends import StoreBackend

store = InMemoryStore()
backend = StoreBackend(store=store, namespace=("shared_files",))

agent = create_deep_agent(model=model, backend=backend)

# 文件在不同 thread 之间共享（只要使用同一个 store）

生产环境搭配 PostgreSQL Store：

from langgraph.store.postgres import PostgresStore

store = PostgresStore.from_conn_string("postgresql://...")
backend = StoreBackend(store=store, namespace=("knowledge_base",))
agent = create_deep_agent(model=model, backend=backend)

ContextHubBackend：用 LangSmith Hub 当存储（0.6.0 新增）

如果你已经在用 LangSmith，ContextHubBackend 省掉了单独部署一个 LangGraph store 的麻烦——它把 agent 的文件（技能、记忆、其他需要持久化的上下文）直接存成 LangSmith Hub 上的 commit。

from deepagents.backends import ContextHubBackend

backend = ContextHubBackend() # 走 LangSmith 凭据
agent = create_deep_agent(model=model, backend=backend)

它真正的价值在每次写入都带版本历史：skill 和 memory 这类文件最需要的就是「改错了能回退、能看出是谁在什么时候改的」，而这些能力在 Hub 上是现成的。代价是绑定了 LangSmith，纯本地或自托管场景还是用 StoreBackend。

4.8 权限控制

通过 permissions 参数精细控制文件系统访问：

agent = create_deep_agent(
 model=model,
 backend=backend,
 permissions=[
 {"path": "/workspace/*", "operations": ["read", "write", "edit"], "mode": "allow"},
 {"path": "/memory/*", "operations": ["read", "write"], "mode": "allow"},
 {"path": "/system/*", "mode": "deny"},
 {"path": "/*", "operations": ["read"], "mode": "allow"},
 {"path": "/*", "operations": ["write", "edit", "delete"], "mode": "interrupt"},
 ],
)

权限模式：

模式	行为
`allow`	直接放行
`deny`	直接拒绝，返回错误信息给 agent
`interrupt`	暂停执行，等待人工审批

权限规则按顺序匹配，第一条匹配的规则生效。

第五章：子智能体

子智能体是 DeepAgents 最有特色的能力之一。核心思想：主 agent 通过 task 工具把一个任务委派给一个拥有独立上下文窗口的子 agent。主 agent 只看到子 agent 的最终输出，不会看到子 agent 的中间过程。

这解决了长任务中的关键问题：上下文污染。当主 agent 执行搜索、阅读、分析等中间步骤时，会产生大量 token。如果这些 token 都堆在主 agent 的上下文里，很快就会超出限制或降低推理质量。子智能体隔离了这些噪音。

5.1 预配置子智能体

from deepagents import create_deep_agent
from deepagents.subagents import SubAgent

researcher = SubAgent(
 name="research-agent",
 description="负责搜索和整理信息，输出结构化研究报告",
 system_prompt="你是一个信息研究员。用 web_search 和 read_file 工具完成调研任务。",
 model="openai:gpt-5.5", # 子智能体可以用不同模型
 tools=[web_search],
)

analyst = SubAgent(
 name="data-analyst",
 description="负责数据分析和可视化",
 system_prompt="你是一个数据分析师。用 Python 分析数据，生成报告。",
 model="anthropic:claude-sonnet-4-6",
 tools=[execute_python, read_file],
)

agent = create_deep_agent(
 model="openai:gpt-5.5",
 subagents=[researcher, analyst],
 system_prompt="你是一个团队负责人。用 task 工具委派任务给子智能体。",
)

当主 agent 判断需要调研时，会调用：

{
 "tool": "task",
 "args": {
 "description": "调研 LangGraph 最新特性并输出报告",
 "subagent_type": "research-agent"
 }
}

5.2 自定义子智能体（传入编译后的 LangGraph）

任何 LangGraph CompiledStateGraph 都可以作为子智能体传入：

from langgraph.graph import StateGraph, MessagesState, END

# 构建一个自定义图
workflow = StateGraph(MessagesState)
workflow.add_node("analyze", analyze_node)
workflow.add_node("report", report_node)
workflow.set_entry_point("analyze")
workflow.add_edge("analyze", "report")
workflow.add_edge("report", END)
custom_graph = workflow.compile()

agent = create_deep_agent(
 model=model,
 subagents=[
 {
 "name": "custom-analyst",
 "description": "自定义分析管道",
 "graph": custom_graph,
 }
 ],
)

5.3 主/子上下文隔离原理

主 Agent 上下文 子 Agent 上下文
┌─────────────────────┐ ┌─────────────────────────────┐
│ system prompt │ │ 子智能体的 system prompt │
│ user message │ │ task description (作为输入) │
│ ... 历史消息 ... │ │ 子智能体的工具和文件系统 │
│ tool: task(...) │──委派──────────→│ │
│ │ │ (子 agent 内部循环) │
│ │←───────────────│ 最终输出（文本摘要） │
│ tool result │ └─────────────────────────────┘
│ ... 继续 ... │
└─────────────────────┘

子 agent 看不到主 agent 的对话历史，只看到任务描述。
主 agent 看不到子 agent 的中间 tool calls、搜索结果、文件内容。
子 agent 的文件系统与主 agent 共享（默认使用同一个 backend）。
如果子 agent 需要向主 agent 传递大文件，通过文件系统写入，主 agent 用 read_file 读取。

5.4 什么时候用子智能体

场景	是否需要子智能体
简单搜索 + 回答	不需要，一个 agent + web_search 就够
多步调研：搜索多个主题、阅读多个来源、综合报告	需要——用 researcher 子智能体隔离搜索噪音
多文件代码修改	需要——用 coder 子智能体隔离文件操作
多源数据采集和分析	需要——不同子智能体处理不同数据源
单一任务，不需要委派	不需要，直接用主 agent

5.5 异步子智能体：并行委派

DeepAgents 同时提供同步和异步两套接口。当需要并行处理多个独立任务时，可以在异步运行环境中用 asyncio.gather 同时发起多个调用，每个子智能体在自己的隔离上下文中工作，主流程只汇总最终结果。

import asyncio

# 同一 agent 的多个独立任务并行执行
results = await asyncio.gather(
 agent.ainvoke({"messages": [("user", "研究主题 A")]}, config),
 agent.ainvoke({"messages": [("user", "研究主题 B")]}, config),
)

如果子智能体内部执行的是 I/O 密集操作（网络搜索、文件读写），并行能显著缩短总耗时。注意每个并行调用会消耗独立的模型调用和 token 配额；asyncio.gather 默认在任一任务异常时取消全部，生产代码建议加 return_exceptions=True 后逐个检查。

5.6 多级子智能体

子智能体的 subagents 字段可以继续传入子智能体配置，形成"主 agent → 一级子 agent → 二级子 agent"的层级结构。每一层都有独立的上下文窗口，适合大型项目中"项目经理 → 领域专家 → 执行者"的分工模式。

deep_researcher = SubAgent(
 name="deep-researcher",
 model="openai:gpt-5.5",
 system_prompt="深入研究并写报告",
 subagents={
 "subagents": [
 SubAgent(
 name="fact-checker",
 model="openai:gpt-5.5",
 system_prompt="验证研究结论中的关键事实",
 ),
 ],
 },
)

层级不宜过深（建议不超过 2-3 层）：每加一层，主 agent 看到的信息就更间接，且 token 消耗按乘数增长。

第六章：上下文管理

DeepAgents 内置了两层上下文管理机制：摘要压缩和大工具输出转存。

6.1 SummarizationMiddleware：对话摘要压缩

当对话的 token 数超过阈值时，SummarizationMiddleware 会：

将旧消息替换为一条摘要消息
将完整的旧消息转存到文件系统（路径如 /conversation_history/{message_id}.json）
保留最近的消息在上下文中

压缩前：
[sys] [msg1] [msg2] [msg3] [msg4] [msg5] ... [msgN]
 ↑ 全部保留在上下文中

压缩后：
[sys] [摘要消息（包含历史概要+文件路径）] [msgN-2] [msgN-1] [msgN]
 ↑ 完整历史在 /conversation_history/

阈值配置：

from deepagents import create_deep_agent
from deepagents.middleware.summarization import SummarizationMiddleware

agent = create_deep_agent(
 model=model,
 tools=tools,
 middleware=[
 SummarizationMiddleware(
 token_threshold=100000, # 超过 100k token 触发压缩
 keep_messages=10, # 保留最近 10 条消息
 )
 ],
)

阈值默认值根据模型的最大输入 token 自动计算（官方口径是达到模型上下文窗口的约 85%）。例如：

GPT-5（128k context）→ 阈值约 100k token
Claude（200k context）→ 阈值约 160k token
回退方案：保留最近 20 条消息

按需压缩：让 agent 自己决定什么时候压

自动摘要只在逼近阈值时才动手，但有些场景你想让它主动在任务边界处压缩——比如一个子任务刚交付完，历史已经没用但离阈值还远。

加一个 compact_conversation 工具就能做到：

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import create_summarization_tool_middleware

backend = StateBackend # 用默认后端时这样写

agent = create_deep_agent(
 model=model,
 middleware=[create_summarization_tool_middleware(model, backend)],
)

注意这不是替代品：加上它并不会关掉 85% 的自动压缩，两者共用同一个摘要引擎和状态。自定义中间件会被插到 PatchToolCallsMiddleware 之后（也就是 2.1 节栈里的位置 7）。

6.2 大工具输出转存

FilesystemMiddleware 监控所有工具的输出。当输出超过阈值（默认 20000 token）时：

将完整输出写入文件系统（路径如 /large_tool_results/{tool_call_id}.txt）
在上下文中只保留摘要消息：[输出过大，已转存到 /large_tool_results/xxx.txt，请用 read_file 读取]

# 你可以自定义阈值
from deepagents.middleware.filesystem import FilesystemMiddleware

fs_mw = FilesystemMiddleware(
 large_output_threshold=10000, # 10000 token 超限
 large_output_dir="/my_tool_results",
)

agent = create_deep_agent(model=model, middleware=[fs_mw])

6.3 记忆与跨会话

通过 memory 参数加载 AGENTS.md：

agent = create_deep_agent(
 model=model,
 tools=tools,
 memory="/path/to/AGENTS.md", # 启动时注入到系统提示词
)

对于需要动态更新的长期记忆，使用 StoreBackend：

from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
memory_backend = StoreBackend(store=store, namespace=("agent_memory",))

agent = create_deep_agent(
 model=model,
 backend=memory_backend,
 system_prompt="你是一个有记忆的助手。在 /memory 目录中维护长期记忆。",
)

Agent 可以通过文件工具读写 /memory/ 目录，实现跨会话的记忆更新。

第七章：Skills（技能系统）

Skills 是 DeepAgents 的渐进式披露机制——将复杂的指令和工具组合打包成可复用的模块，按需加载。

7.1 基本用法

每个技能是一个目录，包含一个 SKILL.md 文件：

my_skills/
├── code-review/
│ └── SKILL.md
├── data-viz/
│ ├── SKILL.md
│ └── templates/
│ └── chart.py
└── web-research/
 └── SKILL.md

SKILL.md 的格式：

---
name: code-review
description: 对代码库进行系统性审查，检查安全性、性能、可维护性
---

## 步骤

1. 读取目标文件列表（用 glob 工具）
2. 逐一读取关键文件
3. 检查以下方面：
 - 安全性：SQL注入、XSS、不安全的反序列化
 - 性能：N+1 查询、内存泄漏、不必要的全表扫描
 - 可维护性：函数长度、重复代码、缺失的类型注解
4. 用 write_file 工具输出审查报告到 /reports/code-review-{date}.md

## 工具

优先使用 grep 搜索特定模式，用 read_file 读取上下文。

agent = create_deep_agent(
 model=model,
 tools=tools,
 skills="/path/to/my_skills",
)

SkillsMiddleware 会将每个技能的 name 和 description 注入系统提示词。Agent 判断当前任务匹配某个技能时，会主动 read_file 读取该技能的完整指令。

7.2 为什么是"渐进式披露"

如果所有技能的完整内容都塞在系统提示词里，token 浪费严重。渐进式披露的设计是：

系统提示词只包含元数据（name + description），几十个 token 每技能。
完整指令在文件系统中，agent 按需读取。
10 个技能的元数据 ≈ 300 token，比全量内容（可能几千 token）节省 90% 以上。

7.3 带资源的技能

技能目录中可以包含额外文件（模板、脚本、配置等），agent 可以通过文件系统工具访问：

my_skills/
└── report-generator/
 ├── SKILL.md
 ├── templates/
 │ ├── report_template.md
 │ └── chart_template.py
 └── config.yaml

Agent 读取 SKILL.md 后，可以根据指令进一步读取 templates/ 中的文件。

7.4 社区技能示例：研究评估评分标准

官方仓库提供了多个可复用的技能示例。下面是一个"研究评估"技能（rubrics 模式）的典型结构——把评审专家的评分维度固化成可复用的指令文件：

---
name: evaluate-research
description: 用评分标准评估研究报告质量
---

## 评分标准

按以下维度评估研究报告（每项 1-5 分）：

1. **事实准确性**：关键事实是否有可靠来源支撑
2. **逻辑连贯性**：结论是否从证据自然推出
3. **完整性**：是否遗漏了重要角度
4. **可操作性**：读者能否据此做出决策

## 流程

1. 阅读研究报告全文
2. 逐项打分并给出具体依据
3. 汇总总分和改进建议

将此文件放入技能目录后，agent 在收到"评估报告"类任务时会自动加载该技能。你可以基于自己的领域编写类似的评分模板——技能系统的本质就是把"怎么做"的专家知识封装成可复用的指令文件。

第八章：Human-in-the-Loop（人机协作）

DeepAgents 允许在工具调用前暂停，等待人工决策。这在生产环境中至关重要——你不希望 agent 在没有人工审核的情况下执行危险操作（删除文件、发送邮件、执行数据库变更等）。

8.1 `interrupt_on` 参数

agent = create_deep_agent(
 model=model,
 tools=[send_email, delete_record, web_search, write_file],
 interrupt_on={
 "send_email": {"allowed_decisions": ["approve", "edit", "reject"]},
 "delete_record": {"allowed_decisions": ["approve", "reject"]},
 },
)

# 第一次 invoke 会触发中断
result = agent.invoke({"messages": [...]})

# 检查是否中断
if result["__interrupt__"]:
 # 获取中断信息
 interrupt_info = result["__interrupt__"][0]
 print(f"工具: {interrupt_info.value['action_request']['action']}")
 print(f"参数: {interrupt_info.value['action_request']['args']}")

 # 人工决策
 human_decision = interrupt_info.value["resume"]
 # 或者用 resume 重新启动
 resumed = agent.invoke(
 {"__interrupt__": [{"resume": {"type": "accept"}}]},
 config=config,
 )

8.2 通过 permissions 实现文件操作审批

agent = create_deep_agent(
 model=model,
 backend=backend,
 permissions=[
 {"path": "/workspace/*", "mode": "allow"},
 {"path": "/*", "operations": ["write", "edit", "delete"], "mode": "interrupt"},
 ],
)

所有 workspace 外的写操作都会触发人工审批。

8.3 中断恢复协议

DeepAgents 的 HITL 基于 LangGraph 的 interrupt 机制。中断后：

图的状态（包括 messages、files）已通过 checkpointer 保存。
agent.invoke() 返回 __interrupt__ 信息。
人工决策通过 agent.invoke() resume：

config = {"configurable": {"thread_id": "session-1"}}

# 第一次调用，触发中断
result1 = agent.invoke({"messages": [...]}, config=config)

# 检查中断并恢复
if "__interrupt__" in result1:
 decision = input("批准/编辑/拒绝？(approve/edit/reject): ")
 result2 = agent.invoke(
 Command(resume={"type": decision}),
 config=config,
 )

支持的决策类型：

决策	行为
`{"type": "accept"}`	批准，继续执行工具调用
`{"type": "edit", "args": {...}}`	编辑参数后继续执行
`{"type": "reject", "message": "..."}`	拒绝，将拒绝理由传回给 agent
`{"type": "respond", "message": "..."}`	不执行工具，向 agent 提供额外信息

第九章：流式输出与中间过程

DeepAgents 基于 LangGraph，支持多种流式模式：

9.1 流式 token

from langchain_core.messages import AIMessageChunk

config = {"configurable": {"thread_id": "session-1"}}

for event in agent.stream(
 {"messages": [{"role": "user", "content": "分析这份数据"}]},
 config=config,
 stream_mode="messages",
):
 # event 是 (message_chunk, metadata) 元组
 msg_chunk, metadata = event
 if hasattr(msg_chunk, "content") and isinstance(msg_chunk.content, str):
 print(msg_chunk.content, end="", flush=True)

9.2 流式工具调用

for event in agent.stream(
 input_data,
 config=config,
 stream_mode="updates",
):
 # 每个节点的更新
 for node_name, node_update in event.items():
 print(f"节点: {node_name}")
 if "messages" in node_update:
 for msg in node_update["messages"]:
 print(f" {msg.type}: {msg.content[:100] if isinstance(msg.content, str) else msg.content}")

9.3 流式文件操作

通过 stream_mode="updates"，可以看到文件系统的变化：

for event in agent.stream(
 input_data,
 config=config,
 stream_mode="updates",
):
 for node_name, node_update in event.items():
 if "files" in node_update:
 print(f"文件变化: {node_update['files'].keys()}")

9.4 事件流（v3）：`stream_events` 与类型化投影

上面几种 stream_mode 是 LangGraph 的原始流式接口——你拿到的是 dict，要自己判断这一块是什么。LangGraph 1.2.0 / DeepAgents 0.6.0 起多了一套更适合应用层写代码的东西：事件流（event streaming），传 version="v3" 开启。

核心变化是：一次 run 产出的事件流被归一化后，经过一层 transformer 管线，暴露成几个带类型的投影，可以同时被多个消费者读——读 stream.messages 不会消耗 stream.values 需要的事件。

stream = agent.stream_events(
 {"messages": [{"role": "user", "content": "分析这份数据"}]},
 version="v3",
)

# 只看模型输出：token 级
for message in stream.messages:
 print(str(message.text), end="", flush=True)

# 最终状态
final_state = stream.output

可用的投影：

投影	用途
`stream`	遍历所有协议事件（原始层）
`stream.messages`	模型消息与 token 增量，另有 `.reasoning` 和 `.tool_calls`
`stream.values`	每一步之后的状态快照，`stream.output` 拿最终值
`stream.subgraphs`	发现并观察嵌套图/子智能体执行
`stream.interrupts` / `stream.interrupted`	人机协作中断的载荷与判定
`stream.extensions`	自定义 transformer 的投影

对 DeepAgents 来说，stream.subgraphs 特别有用——子智能体的执行会作为嵌套作用域出现在这里，直接看 subgraph.graph_name 和 subgraph.path 就行，不用去解析 namespace 字符串：

stream = agent.stream_events(input_data, config=config, version="v3")

for subgraph in stream.subgraphs:
 print(subgraph.graph_name, subgraph.path)
 for message in subgraph.messages:
 print(message.text)

异步场景下可以并发消费多个投影：

stream = await agent.astream_events(input_data, version="v3")

async def consume_messages():
 async for message in stream.messages:
 print(f"[llm] node={message.node}")

async def consume_subgraphs():
 async for subgraph in stream.subgraphs:
 print(f"[subgraph] path={subgraph.path}")

await asyncio.gather(consume_messages(), consume_subgraphs())

同步代码想在严格的到达顺序里混着读多个投影，用 stream.interleave(...)：

for name, item in stream.interleave("values", "messages", "subgraphs"):
 if name == "values":
 print(f"[state] keys={list(item)}")
 elif name == "messages":
 print(f"[llm] node={item.node}")
 elif name == "subgraphs":
 print(f"[subgraph] path={item.path}")

底层通道（event["method"]）有 values、updates、messages、tools、lifecycle、checkpoints、input、tasks、custom。其中 messages 是按 content block 建模的，事件序列固定为 message-start → content-block-start → content-block-delta → content-block-finish → message-finish，文本、推理、工具调用、多模态内容都有显式边界，不再依赖各家 provider 的格式。

v1 和 v2 的写法保持兼容，没有破坏性变更——现有代码不用动，新代码建议直接从 v3 起步。

第十章：生产部署

10.1 部署选项

方案	适用场景
LangGraph Platform	托管部署，LangSmith 集成，自动扩缩
Docker + 自建	需要完全控制的私有化部署
Serverless（Vercel/Modal/Cloud Run）	事件驱动、低流量场景
LangSmith Deployment	与 LangSmith 评估和监控深度集成

10.2 Docker 部署示例

FROM python:3.12-slim
WORKDIR /app

# 安装依赖
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen

# 复制代码
COPY . .

# 暴露端口
EXPOSE 8000

# 启动（LangGraph serve）
CMD ["uv", "run", "langgraph", "serve", "--host", "0.0.0.0", "--port", "8000"]

10.3 环境变量

# 模型 API Key
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-...

# LangSmith（可选，但强烈推荐）
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=my-agent

# 数据库（生产 checkpointer）
DATABASE_URL=postgresql://user:pass@host:5432/db

10.4 安全模型

DeepAgents 遵循"信任 LLM"模型。Agent 可以做任何工具允许的事情。安全边界必须在你这一侧强制执行：

后端层面：使用 SandboxBackend 或 FilesystemBackend 的 root_dir 限制 agent 能访问的目录。
权限层面：使用 permissions 参数控制读写和删除操作。
工具层面：不要暴露你不想让 agent 执行的工具。
HITL 层面：对危险操作（删除、发送、支付）设置 interrupt_on。
网络层面：如果 agent 有 web 访问能力，确保它不能访问内网端点。

10.5 可观测性

LangSmith 集成：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=your_key
export LANGSMITH_PROJECT=production-agent

设置环境变量后，所有 agent 调用自动产生 trace。无需改代码。

10.6 评测

from langsmith import Client

client = Client()

# 创建评测数据集
dataset = client.create_dataset("deep-agents-eval")
client.create_examples(
 dataset_id=dataset.id,
 inputs=[
 {"messages": [{"role": "user", "content": "调研 X 并写报告"}]},
 {"messages": [{"role": "user", "content": "修复 bug #123"}]},
 ],
)

# 运行评测
client.evaluate(
 agent,
 data=dataset.id,
 evaluators=[
 # 自定义评估器
 lambda outputs, reference: {"accuracy": compute_match(outputs, reference)},
 ],
)

第十一章：实战模式

11.1 研究智能体

from deepagents import create_deep_agent
from deepagents.subagents import SubAgent
from langchain.tools import tool

@tool
def web_search(query: str) -> str:
 """搜索互联网获取信息"""
 # 接入 Tavily / Bocha / 百炼 WebSearch MCP
 ...

@tool
def web_extract(url: str) -> str:
 """抽取网页正文内容"""
 ...

research_subagent = SubAgent(
 name="researcher",
 description="搜索和整理信息",
 system_prompt="你是一个信息研究员。用 web_search 和 web_extract 完成调研。",
 model="openai:gpt-5.5",
 tools=[web_search, web_extract],
)

agent = create_deep_agent(
 model="openai:gpt-5.5",
 subagents=[research_subagent],
 system_prompt="""你是一个研究助手。
 收到调研任务后，用 task 工具委派给 researcher 子智能体。
 基于子智能体的输出，综合并生成最终回答。""",
)

11.2 代码智能体

from deepagents.backends.filesystem import FilesystemBackend

backend = FilesystemBackend(root_dir="/path/to/repo")

agent = create_deep_agent(
 model="anthropic:claude-sonnet-4-6",
 backend=backend,
 system_prompt="""你是一个代码编辑助手。
 先用 glob 和 grep 了解代码库结构。
 修改代码前先 read_file 阅读上下文。
 修改后用 execute 工具运行测试验证。
 修改必须最小化，不要过度工程化。""",
)

11.3 数据分析智能体

from deepagents.backends import SandboxBackend

backend = SandboxBackend(
 root_dir="/tmp/data_sandbox",
 timeout=300,
)

agent = create_deep_agent(
 model="openai:gpt-5.5",
 backend=backend,
 system_prompt="""你是一个数据分析师。
 先用 execute("ls /") 查看数据文件。
 用 execute("python -c \"...\\"") 或 execute("head -n 100 data.csv") 探索数据。
 用 execute("python analysis.py") 执行分析脚本。
 用 write_file 生成分析报告。""",
)

11.4 混合模式：DeepAgents + 百炼 Responses API

当你需要 DeepAgents 的 harness 能力 + 百炼的 web_search：

import os
from openai import OpenAI
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

# 百炼 Responses API 客户端（用于 web_search）
bailian = OpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

@tool
def bailian_web_search(query: str) -> str:
 """搜索互联网获取最新信息（使用百炼 web_search）"""
 response = bailian.responses.create(
 model="qwen3-max",
 input=query,
 tools=[{"type": "web_search"}],
 )
 # 提取搜索结果
 results = []
 for item in response.output:
 if getattr(item, "type", None) == "web_search_call":
 results.append(str(item))
 elif getattr(item, "type", None) == "message":
 for content in getattr(item, "content", []):
 if hasattr(content, "text"):
 results.append(content.text)
 return "\n".join(results)

# DeepAgents 走 Chat Completions
model = ChatOpenAI(
 model="qwen-plus",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

agent = create_deep_agent(
 model=model,
 tools=[bailian_web_search],
 system_prompt="你是一个研究助手。用 bailian_web_search 查询最新信息。",
)

第十二章：协议对比总结

12.0 Deep Agents Code（dcode）

除了可编程的 Python/JS 库，LangChain 还提供了 Deep Agents Code（dcode）——一个预构建的终端编码智能体，定位类似 Claude Code 或 Cursor CLI，底层就是 DeepAgents harness。它让你不用写代码就能体验文件系统、子智能体、上下文管理等全部能力。

# 一键安装
curl -LsSf https://langch.in/dcode | bash

# 在项目目录中启动
cd your-project
dcode

dcode 使用任何支持 tool calling 的 LLM 作为后端。对于想先"用"再"编"的用户，建议先试 dcode 感受 harness 行为，再用 create_deep_agent 定制自己的流程。

dcode 迭代很快（几乎每周发版），近期（0.1.67 / 0.1.68）值得关注的更新：

工作区隔离增强：项目策略按 workspace 解析、dotenv 按 workspace 作用域隔离、LangSmith 认证与 tracing 隔离；跨工作区切换时复用 server 并在重启前请求确认。
模型支持：新增 Fireworks GLM-5.3 / GLM-5.3 Flash 的用量计价，推荐模型列表纳入 GLM 5.3 系列。
subagent 行为：general-purpose 子智能体默认以 fork 模式运行（继承完整上下文），并支持 fresh subagent 与按任务选择工具。

官方文档：https://docs.langchain.com/deepagents-code

12.1 DeepAgents 的模型协议

DeepAgents 对模型的唯一要求是 tool calling。它不关心底层是 Chat Completions 还是 Responses API，只要 LangChain ChatModel 能完成以下循环：

发送 [system, user, assistant(tool_calls), tool(results)] → 模型返回 tool_calls 或 text → 循环

Chat Completions 兼容端点（OpenAI、DashScope、Ollama、vLLM）：直接用 ChatOpenAI。
Responses API（OpenAI / 百炼）：通过 init_chat_model("openai:...", use_responses_api=True)。
Anthropic：直接用 ChatAnthropic 或 "anthropic:claude-sonnet-4-6"。
本地模型：ChatOllama 或 ChatVLLM。

12.2 与百炼 Responses API 的关系

维度	DeepAgents + Chat Completions	百炼 Responses API
协议	Chat Completions（`messages`）	Responses（`input`）
工具调用	客户端执行（LangChain tool calling）	服务端内置（web_search 等）
Agent 循环	DeepAgents 框架管	你自己管
搜索	需要自己包装工具	服务端内置
文件系统	内置	无
子智能体	内置	无
上下文管理	内置	无
HITL	内置	无

12.3 选型决策树

需要 DeepAgents 的 harness 能力？
├─ 是 → 需要 web_search？
│ ├─ 是 → 自己包装搜索为 function tool（推荐）
│ │ 或混合模式（DeepAgents + 百炼 Responses API）
│ └─ 否 → 直接用 DeepAgents + Chat Completions
└─ 否 → 需要服务端内置工具（web_search 等）？
 ├─ 是 → 直接用百炼 Responses API
└─ 否 → LangChain create_agent / LangGraph

12.4 RubricMiddleware：自评迭代循环

DeepAgents 内置了 RubricMiddleware，让你用"评分标准"定义什么叫做完成。当 agent 准备结束回复时，中间件会调用一个独立的"评分器"子智能体，根据 rubric 逐条检查 agent 的输出。如果评分器返回 needs_revision，其反馈会作为 HumanMessage 注入上下文，agent 循环继续——直到评分器返回 satisfied、failed 或达到最大迭代次数。

from deepagents import create_deep_agent
from deepagents.middleware import RubricMiddleware

rubric_mw = RubricMiddleware(
 rubric=[
 {"criterion": "所有关键论断都有来源引用", "weight": 3},
 {"criterion": "结论与证据逻辑一致", "weight": 2},
 {"criterion": "无事实错误", "weight": 3},
 ],
 grader_model="openai:gpt-5.5",
 max_iterations=3,
)

agent = create_deep_agent(
 model="openai:gpt-5.5",
 middleware=[rubric_mw],
 system_prompt="你是一个研究助手，写完报告后自我检查再提交。",
)

这个模式非常适合对输出质量有硬性要求的场景（合规文档、技术报告、代码审查），把"人工再审一遍"变成可编程的自动质量门。

12.5 官方示例集导读

GitHub 仓库的 examples/ 目录包含十多个端到端案例，按学习优先级推荐如下：

示例	亮点
`content-builder-agent`	用 Memory + Skills + Subagents 三原语构建内容写作 agent，最适合入门
`deep_research`	完整的深度研究 agent（多轮搜索 + 报告生成），展示实际 token 管理
`text-to-sql-agent`	自然语言 → SQL，展示 planning + filesystem + subagent 组合
`rubric_middleware`	RubricMiddleware + LangSmith trace，展示自评迭代全流程
`async-subagent-server`	异步子智能体 + 服务端部署，生产级 FastAPI 集成
`ralph_mode`	Ralph 自主循环模式（Geoff Huntley），`while :; do agent; done` 的 DeepAgents 实现
`better-harness`	用一个 DeepAgent 优化另一个 agent harness 的元循环（harness engineering）

建议先跑 content-builder-agent 理解三原语（Memory / Skills / Subagents），再按需深入其他案例。

附录

A. 常用环境变量

变量	说明
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`DASHSCOPE_API_KEY`	阿里云百炼 API key
`LANGSMITH_TRACING`	启用 LangSmith trace
`LANGSMITH_API_KEY`	LangSmith API key
`LANGSMITH_PROJECT`	LangSmith 项目名
`LANGCHAIN_TRACING_V2`	启用 LangSmith trace（旧变量名）
`LANGCHAIN_API_KEY`	LangSmith API key（旧变量名）
`LANGCHAIN_PROJECT`	LangSmith 项目名（旧变量名）

B. 版本注意事项

deepagents 0.7.x 是当前最新版本系列（最新 0.7.15，2026-09-16），尚未发布 0.8 或 1.0。
0.5.x → 0.6.x 有重大变化：SubAgent 类型变化、response_format 新增，并且消息历史与 agent 文件切到 DeltaChannel 持久化，此变更不可回滚（见 3.5 节）。
0.6.x → 0.7.x 新增了 skills、memory、permissions、delete 工具、FilesystemMiddleware 工具白名单，同时做了一次提示词瘦身（见 2.3 节）。
0.7.13 → 0.7.14 → 0.7.15 都是修补性质：read_file 输出格式调整、edit_file 拒绝空 old_string、ls/glob 字符计数修正、无 ID 的工具结果转存改用唯一路径、subagent state key 传递修复。
如果从 0.3.x 升级，SubAgent 已从 dict 改为类型化对象，create_deep_agent 的参数名有变化。
0.x 版本 API 变动快，生产环境建议锁定版本（uv add deepagents==0.7.15）。

本文覆盖的版本快照（截至 2026-09-21）

包	本文基准版本	发布日期	备注
`deepagents`（Python）	0.7.15	2026-09-16	核心库，本文主体内容
`deepagents-code`（dcode）	0.1.72	2026-09-21	终端编码智能体，见 12.0 节
`deepagents-talon`	0.0.8	2026-09-11	独立发布，本文未覆盖
`langchain-quickjs`	0.3.7	2026-09-06	JS 运行时，`CodeInterpreterMiddleware` 依赖它，本文未展开
`langchain`	1.4.0	2026-09-01	MCP 支持已内建进 `langchain.mcp`
`langchain-mcp-adapters`	—	—	已被 `langchain.mcp` 取代，不再维护
`deepagents.js`（JS/TS）	—	—	独立仓库，见附录 C

下次更新检查清单

查看 GitHub Releases 确认 deepagents 最新 minor 版本（当前 0.7.x；如果发布 0.8 或 1.0，优先检查 breaking changes）。
对比 CHANGELOG（或 release notes），重点看：
- 新增/移除的中间件（libs/deepagents/deepagents/middleware/ 目录）
- create_deep_agent 签名变化
- 新增的 examples 目录
检查 deepagents-code 是否有新 major 功能（dcode 迭代很快，几乎每周发版）。
确认本文引用的文档链接是否仍然有效（LangChain 文档路径经常重组）。
如果有新的 middleware 或新的 examples，优先补充到第 2 章（中间件详解）和 12.5 节（示例导读）。

C. 生态与跨语言

JavaScript/TypeScript：DeepAgents 提供了 deepagents.js 库（GitHub），适合在 Node.js 环境中构建 agent。
Deep Agents Code：终端编码智能体，安装命令见 12.0 节。

D. 相关资源

本文基于 DeepAgents 0.7.15 版本编写，2026 年 9 月。API 在 1.0 之前可能变化，请以官方文档为准。

Langchain-RAG实战教程

Tue, 06 May 2025 11:05:13 +0800

LLM 有两个先天限制：知识停在训练截止日期，你的私有文档、内部资料也不在它的训练语料里。直接问，轻则答"不知道"，重则一本正经地编。RAG（Retrieval Augmented Generation）就是针对这两个问题的标准解法：先从你自己的文档集合里检索出与问题最相关的几段文本，连同问题一起交给模型，让它基于给定材料作答。

这篇文章以我实际跑通的一套为例：阿里云百炼提供的 Embedding 模型和 qwen 系模型，LangChain 做编排，Chroma 做向量库。完整代码在同目录 main.py，知识库是 example_doc.txt（一篇约一万字符的 LangChain 教程文本），运行截图见下文。正文以现在还能跑的写法为准；当年 0.1 时代的老 API（RetrievalQA、get_relevant_documents() 等）单独开一节做注记，不占主线。

动手之前先回答选型问题：什么时候用 RAG，什么时候微调。

维度	RAG	微调
知识更新	换文档立即生效	需重新训练
擅长	私有知识问答、事实性回答	固定的风格、格式、领域行为
成本	主要是检索和推理开销	算力 + 数据准备 + 训练周期
可解释性	回答可溯源到具体文档	难以溯源

我的判断：知识层面的问题优先 RAG，微调解决的是"怎么说话"而不是"知道什么"。两者不冲突，可以叠加，但大多数场景先把 RAG 做好就够用了。

RAG 的核心组件：一条数据流

一个 LangChain RAG 应用的组件可以串成一条数据流看：

原始文档
 │ Document Loaders（加载）
 ▼
Document（整篇 page_content + metadata）
 │ Text Splitters（分割）
 ▼
chunks（小块文本，继承 metadata）
 │ Embedding 模型（向量化）
 ▼
向量 → Vector Store（落库）
 │ 用户提问同样转向量，相似度检索 top-k（Retriever）
 ▼
问题 + 相关 chunks（拼进 Prompt）
 │ LLM（生成）
 ▼
基于文档的回答

对应到具体组件：

组件	职责	本文用的实现
Document Loaders	从 txt/PDF/网页等来源读入文档	`TextLoader`
Text Splitters	把长文档切成语义连贯的小块	`RecursiveCharacterTextSplitter`
Embedding 模型	文本转向量	百炼 `text-embedding-v2`
Vector Store	存向量，提供相似度检索	Chroma
Retriever	统一检索接口，取 top-k	`as_retriever()`
LLM	基于上下文生成回答	qwen-plus（OpenAI 兼容模式）
链（编排）	把上面串成完整流程	LCEL

前四类组件是"建索引"阶段，Retriever 和链是"查询"阶段。索引建一次可以服务无数次查询，知识更新只需重建索引——这是 RAG 相对微调灵活的根源。

实战：百炼 + LangChain + Chroma 端到端

阿里云百炼（Model Studio）是阿里云的大模型服务平台，qwen 系模型和 text-embedding 系向量模型都能通过 DashScope API 调用，并且提供 OpenAI 兼容接口——chat 侧可以直接用 langchain-openai 的 ChatOpenAI 接入，不需要专门的 SDK 封装。

源文件与运行结果

说明：同目录的 main.py 是当时跑通的原始代码，里面还保留着 0.1 时代的写法（from langchain.text_splitter import ...、get_relevant_documents()、vectorstore.persist()、RetrievalQA）。本文正文按当前版本的写法整理过，对照源码阅读时注意区分。

源文件	说明
example_doc.txt	知识库文本，一篇约一万字符的 LangChain 教程
main.py	完整可运行代码

准备：依赖与 API Key

pip install langchain langchain-community langchain-openai langchain-text-splitters chromadb dashscope python-dotenv

dashscope 是 DashScopeEmbeddings 的依赖；如果嵌入走 OpenAI 兼容接口（见下文），这个包也可以不装。去百炼平台申请 API Key，写入脚本同目录的 .env：

DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx"

import os
from dotenv import load_dotenv

load_dotenv()

模型名以百炼的模型列表为准：https://help.aliyun.com/zh/model-studio/getting-started/models

加载与分割

from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter

loader = TextLoader("./example_doc.txt", encoding="utf-8")
documents = loader.load()

text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
texts = text_splitter.split_documents(documents)
print(f"文档被分割成 {len(texts)} 个文本块")

两个参数直接决定检索质量：chunk_size 是每块的最大字符数，太大则一块里混进多个主题、检索不精准，太小则上下文碎、嵌入的语义信息不够；chunk_overlap 是相邻块的重叠字符数，用来避免关键句恰好被切断。1000/200 是常见的起步值，值得针对自己的文档实测调整。

读 PDF 把 TextLoader 换成 PyPDFLoader 即可，分割逻辑完全复用。

版本差异：0.1 时代的教程写 from langchain.text_splitter import ...，现在分割器拆到了独立的 langchain_text_splitters 包，老路径已废弃。

嵌入

from langchain_community.embeddings import DashScopeEmbeddings

embeddings_model = DashScopeEmbeddings(model="text-embedding-v2")

# 快速自检：随便嵌一句话，能出向量就说明模型和 Key 都通了
example_embedding = embeddings_model.embed_query("这是一个示例文本，用于测试嵌入模型。")
print(f"向量维度: {len(example_embedding)}")

⚠️ DashScopeEmbeddings 来自 langchain_community（依赖 dashscope SDK），属于 legacy 集成，不保证长期维护。新代码可以直接走百炼的 OpenAI 兼容接口，与本站其他文章的做法一致：

from langchain_openai import OpenAIEmbeddings

embeddings_model = OpenAIEmbeddings(
 model="text-embedding-v2",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 check_embedding_ctx_length=False, # 关掉 OpenAI 特有的长度检查，否则会报错
)

向量库：Chroma

from langchain_community.vectorstores import Chroma

vectorstore = Chroma.from_documents(
 documents=texts,
 embedding=embeddings_model,
 persist_directory="./chroma_db",
)

指定 persist_directory 之后，数据在写入时自动落盘，下次运行用 Chroma(persist_directory="./chroma_db", embedding_function=embeddings_model) 直接加载，不必重建索引。

几个容易踩坑的点：

0.1 时代教程里常见的 vectorstore.persist() 不要再写了。Chroma 早就自动持久化，这个方法在新版集成里已被移除，留着只会报错。
langchain_community.vectorstores 里的 Chroma 是老路径，官方现在推荐独立包：pip install langchain-chroma，然后 from langchain_chroma import Chroma，参数一致。
FAISS 也是常用选择：FAISS.from_documents(texts, embeddings_model) 一行建库，纯内存、速度极快，适合原型验证；需要持久化时自己调 save_local() / load_local()。

检索器

retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

relevant_docs = retriever.invoke("什么是 Langchain?")
print(f"检索到 {len(relevant_docs)} 个相关文档块")
for i, doc in enumerate(relevant_docs):
 print(f"文档 {i+1}: {doc.page_content[:150]}...")

k=3 即取相似度最高的 3 个块。Retriever 是 LangChain 的统一检索接口，向量库、多路召回、压缩检索都实现同一个接口，后面换策略不用改下游代码。

版本差异：老教程里的 retriever.get_relevant_documents(query) 已废弃，统一用 retriever.invoke(query)。

生成模型：qwen-plus

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 model="qwen-plus", # 模型列表: https://help.aliyun.com/zh/model-studio/getting-started/models
)

这是百炼的 OpenAI 兼容模式：langchain-openai 一个包通吃 qwen 系模型（qwen-plus、qwen-max 等），换模型只改 model 字符串，我的 main.py 走的就是这条路。另一条路是 langchain_community 的 ChatTongyi（或更新包里的 langchain-alibaba），同样属于 legacy 集成，除非依赖 DashScope SDK 的特有能力，否则兼容模式这条最省事。

用 LCEL 拼生成链

基础链：检索结果拼成上下文，连同问题一起过 Prompt、LLM、输出解析。

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

template = """请根据以下上下文信息来回答问题。如果你不知道答案，就说你不知道，不要试图编造答案。
用最多三句话来回答，并保持答案简洁。

上下文:
{context}

问题: {question}

有用的回答:"""
prompt = ChatPromptTemplate.from_template(template)

def format_docs(docs):
 return "\n\n".join(doc.page_content for doc in docs)

rag_chain = (
 {"context": retriever | format_docs, "question": RunnablePassthrough()}
 | prompt
 | llm
 | StrOutputParser()
)

answer = rag_chain.invoke("Langchain 的核心组件有哪些？")
print(answer)

拆开看这条链：输入是问题字符串，RunnablePassthrough() 把它原样传给 question；retriever | format_docs 表示先用检索器取文档、再拼成字符串赋给 context；然后依次过 Prompt、LLM，StrOutputParser() 把模型输出解析成纯字符串。整条链由 | 组合，每一段都是 Runnable，天然支持 .invoke()、流式输出和异步。

想同时拿到源文档做溯源，用 RunnablePassthrough.assign 把中间结果挂在字典里：

from operator import itemgetter

rag_chain_with_source = RunnablePassthrough.assign(
 context=itemgetter("question") | retriever | format_docs
).assign(
 answer=(
 {"context": itemgetter("context"), "question": itemgetter("question")}
 | prompt
 | llm
 | StrOutputParser()
 )
)

result = rag_chain_with_source.invoke({"question": "Langchain 的核心组件有哪些？"})
print(result["answer"]) # 生成的回答
print(result["context"]) # 参与生成的检索原文，可用来核对出处

Prompt 里"不知道就说不知道"这句话值得保留——它是压制幻觉的第一道闸门，尤其在检索没命中、上下文里根本没有答案的时候。

历史写法注记：RetrievalQA

这份教程最初是用 RetrievalQA 写的，0.1 时代的标准做法长这样：

# ⚠️ LangChain 1.0 已移除，仅供对照历史代码
from langchain.chains import RetrievalQA

qa_chain = RetrievalQA.from_chain_type(
 llm=llm,
 chain_type="stuff", # 或 "map_reduce" / "refine" / "map_rerank"
 retriever=retriever,
 return_source_documents=True,
)
result = qa_chain.invoke({"query": "请介绍一下 Langchain 的主要功能。"})
print(result["result"])

它把"检索 + 拼 Prompt + 生成"封成一个现成的链，chain_type 决定文档的塞法：stuff 全部塞进一个 Prompt；map_reduce 分块各自作答再合并；refine 逐块迭代修正；map_rerank 分块作答后按置信度挑。当年确实好用，我的 main.py 里跑通的也是它。

LangChain 1.0 把 langchain.chains 里这批 legacy 链整体移除了，RetrievalQA 已不存在。现代等价物就是上文那几行 LCEL——十行不到，换来的是每一步可插拔可调试；要接 Agent 的话，用 create_retrieval_tool 把检索器包成工具交给模型自主调用。老代码迁移时，遇到 from langchain.chains import RetrievalQA 直接按上文重写即可。

进阶检索策略

基础 RAG 跑通后，瓶颈多半出在检索而不是生成。三个常用升级：

MMR：解决"检索回来的块都长一个样"

普通 top-k 检索常返回几个彼此高度相似的块，占满上下文却没带来新信息。MMR（Maximal Marginal Relevance）在"与查询相似"和"彼此不相似"之间做平衡，迭代选点。启用只需换参数：

retriever = vectorstore.as_retriever(
 search_type="mmr",
 search_kwargs={"k": 4, "fetch_k": 20, "lambda_mult": 0.5},
)

fetch_k 是参与 MMR 挑选的候选数（应大于 k），lambda_mult 越接近 1 越偏多样性、越接近 0 越偏相似度。

MultiQueryRetriever：用 LLM 改写查询

用户的提问措辞常常和文档措辞对不上，一路查询召回有限。MultiQueryRetriever 让 LLM 把一个问题从不同角度改写成多个查询，分别检索后合并去重，提升召回：

retriever_multiquery = MultiQueryRetriever.from_llm(
 retriever=vectorstore.as_retriever(search_kwargs={"k": 1}),
 llm=llm,
)

代价是每次检索多一次 LLM 调用，适合召回率明显不足时再上。

SelfQueryRetriever：语义检索 + 元数据过滤

文档带结构化元数据（来源、类别、日期）时，SelfQueryRetriever 用 LLM 把自然语言拆成"语义查询 + 元数据过滤条件"两部分，向量库里同时做相似度和过滤。“找水果相关的文档，只要 doc3 来源的"这类需求，普通向量检索表达不出来，它能。

用法上需要用 AttributeInfo 把元数据字段的名称、类型、描述告诉 LLM，再 SelfQueryRetriever.from_llm(llm=..., vectorstore=..., metadata_field_info=[...]) 构建，且向量库必须支持元数据过滤（Chroma 支持）。

同一方向上还有几个值得知道的名字：ContextualCompressionRetriever（检索后用 LLM 过滤或抽取相关片段，给上下文瘦身）、EnsembleRetriever（多路召回 + RRF 融合，比如 BM25 和向量各一路）、ParentDocumentRetriever（小块检索保精度、返回父块保上下文完整）。检索质量还有两个进阶手段：混合检索（关键词 + 向量）和对 top-k 结果做 Rerank 重排。不用一次全上，哪个指标差修哪个。

怎么知道 RAG 好不好：评估指标

调优之前先有度量，否则改 chunk_size、换嵌入模型全是凭感觉。RAG 的质量要拆成两层看：检索层（该找到的找到了吗）和生成层（找到的材料用对了吗）。两层修法完全不同——检索差该动分割策略和嵌入模型，生成差该动 Prompt 和模型——混在一起调是常见错误。

层	指标	衡量什么
检索	Hit Rate	top-k 结果里包含正确文档的比例
检索	MRR	正确文档排名倒数的平均（第 1 名得 1，第 3 名得 1/3）
检索	Precision@k / Recall@k	返回的 k 条里有多少相关 / 该找到的找到了多少
检索	nDCG@k	带排名位置权重的列表质量
生成	EM（Exact Match）	答案与标准答案完全一致的比例
生成	F1	答案词级精确率/召回率的调和平均，适合抽取式问答
生成	BLEU / ROUGE / METEOR	生成文本与参考答案的重叠度，适合开放式生成
生成	语义相似度	用嵌入模型算答案与参考答案的向量相似度

评估方式从贵到便宜排：

人工评估：质量的金标准，准但不可规模化。
LLM-as-judge：让一个强模型按准确性、相关性、忠实度等维度给答案打分，便宜可规模化，但有自己的偏差（比如偏好长答案），结论要抽检校准。
框架：Ragas 专做 RAG 评估，把忠实度（faithfulness）、答案相关性、上下文精确率/召回率等指标现成化；LangSmith 提供数据集管理、运行评估和版本对比。

这些指标都依赖一个带标准答案的测试集（问题 + 正确出处 + 参考答案）。没有测试集，任何指标都算不出来——这也是多数团队跳过评估的原因。哪怕手工整理二十个有代表性的问题，也够支撑第一轮迭代。

总结

一条 RAG 主线至此完整：加载 → 分割 → 嵌入 → Chroma 落库 → 检索 → LCEL 生成，百炼的模型用 OpenAI 兼容模式接入，一套 langchain-openai 通吃。下一步可以按顺序做这几件事：

把 main.py 里的老写法按本文修正（langchain_text_splitters 导入、invoke()、去掉 persist()、RetrievalQA 换 LCEL），在当前版本的 LangChain 上重跑一遍。
用同一组问题对比不同 chunk_size / chunk_overlap 下的检索质量，别沿用默认值。
检索结果重复单一时，先把 search_type 换成 "mmr"，这是成本最低的升级。
整理一批带标准答案的测试问题，用 Hit Rate / MRR 或直接上 Ragas 建立基线，之后的每次改动都对着基线说话。
需要更精细的召回再考虑 MultiQuery / SelfQuery，需要接 Agent 用 create_retrieval_tool。

进一步阅读：LangChain 官方文档 https://python.langchain.com/

LangChain 进阶 on 扎塔-Zata

LangGraph 实战：StateGraph、手写 ReAct 循环与 Map-Reduce 摘要

LangGraph 实战：StateGraph、手写 ReAct 循环与 Map-Reduce 摘要

1. 基础三件套：StateGraph、State 与条件边

1.1 StateGraph：把应用建成一张状态机

1.2 State 与 Annotated：覆盖还是追加

1.3 MessagesState：内置的消息状态

1.4 条件边：让图自己决定下一步

2. 手写 tool-call 循环：Agent 到底在替你做什么

3. 完整实战：天气助手 ReAct

3.1 环境与依赖

3.2 工具定义：@tool

3.3 模型初始化与工具绑定

3.4 状态与节点

3.5 条件边与图构建

3.6 执行：两轮对话

3.7 六步执行流程梳理

3.8 收尾要点

4. Map-Reduce：超长文本分段摘要

5. 记忆与持久化：MemorySaver 与 thread_id

6. LangGraph 1.1 / 1.2：从"能跑"到"敢上生产"

6.1 节点超时：TimeoutPolicy

6.2 节点级错误处理：error_handler

6.3 图级默认值：set_node_defaults

6.4 优雅停机：RunControl 与 drain

6.5 DeltaChannel：给长线程的 checkpoint 减重

6.6 流式输出换代：事件流（v3）

6.7 类型安全的 invoke / stream（1.1）

7. 版本注记：从 0.x 写法到 LangChain 1.x

版本基线

附：题外话——我试过的 LangChain 知识图谱（不是 LangGraph）

总结

一个订阅更新摘要 Agent 的完整实践：从提示词踩坑到长文本分块

一个订阅更新摘要 Agent 的完整实践：从提示词踩坑到长文本分块

一、第一版管线：从 PromptTemplate 到 JSON 解析

输入与输出

SubscriptionAgent：提示、组链、解析

当时已知的软肋与对策

二、提示词踩坑：一字之差的质变

误判现场

关键改动

第二轮：真实 diff 再验证

复盘

三、超长文本：按变更单元分块，map-reduce 汇总

输出结构：从手写 dict 到 Pydantic

主流程：token 估算与分块决策

分块策略：优先变更单元，字符数兜底

map：逐块抽取

reduce：汇总成最终结果

容错与重试

如实交代：memory 并没有真正生效

四、工程细节清单

总结

溯源

DeepAgents完全指南

DeepAgents 完全指南

第一章：DeepAgents 是什么

1.1 一句话定义

1.2 在 LangChain 生态中的位置

1.3 核心能力一览

1.4 安装

第二章：架构与中间件协议

2.1 中间件栈的完整顺序

2.2 核心中间件详解

FilesystemMiddleware

SubAgentMiddleware

SummarizationMiddleware

PatchToolCallsMiddleware

SkillsMiddleware

MemoryMiddleware

CodeInterpreterMiddleware（Interpreter，beta）

HumanInTheLoopMiddleware

2.3 系统提示词的组装

2.4 HarnessProfile

第三章：create_deep_agent 完整签名

3.1 model 参数

重要：OpenAI 模型的 Responses API 默认行为

接入阿里云百炼（DashScope）

3.2 tools 参数

3.3 system_prompt 参数

6.1 节点超时：`TimeoutPolicy`

6.2 节点级错误处理：`error_handler`

6.3 图级默认值：`set_node_defaults`

6.4 优雅停机：`RunControl` 与 drain

第三章：`create_deep_agent` 完整签名

3.1 `model` 参数

3.2 `tools` 参数

3.3 `system_prompt` 参数

3.4 `response_format` 参数

3.5 `checkpointer` 与持久化

8.1 `interrupt_on` 参数

9.4 事件流（v3）：`stream_events` 与类型化投影