阶段4(上):LangGraph、Function Calling、MCP(SDK 2.x)、Agent 评测与运维、Agent 设计专题;run_examples 设置 RUN_EXAMPLES=1

This commit is contained in:
Shikui Wang committed 2026-10-23 16:06:54 +08:00
1 parent 6650f7eb6d
commit caaec830b3
38 files changed
+3515 -64

No files matched your search

+110
View File
@@ -0,0 +1,110 @@
---
id: ai.langgraph.state-graph
title: LangGraph 状态图:状态、节点、边、条件路由和流式输出
type: lesson
domain: ai
stack: [langgraph]
tags: [LangGraph, StateGraph, reducer, 条件边, 流式输出, stream_mode]
level: intermediate
prerequisites: [ai.function-calling.tool-loop]
est_hours: 3
related: [ai.langgraph.persistence-hitl, ai.agent-design.react-planning, ai.langgraph.interview]
week: [11]
order: 1
---
# LangGraph 状态图:状态、节点、边、条件路由和流式输出
> 基于 langgraph 1.2 编写,API 变化较快,以官方文档为准:https://docs.langchain.com/oss/python/langgraph/overview
## 解释说明
LangGraph 把一个 Agent / 工作流写成**有状态的图**:
| 概念 | 说明 |
| --- | --- |
| **State(状态)** | 一个 `TypedDict`(或 pydantic 模型),所有节点共享。节点返回“要更新的字段”,而不是整个状态 |
| **Reducer(合并函数)** | 决定字段怎么更新。默认覆盖;`Annotated[list, operator.add]` 表示追加;消息列表常用 `add_messages`(按消息 id 追加或替换) |
| **Node(节点)** | 普通函数:输入状态,返回部分更新。可以调用模型、工具、数据库 |
| **Edge(边)** | 固定边 `add_edge(a, b)`;条件边 `add_conditional_edges(a, 路由函数)`,路由函数返回下一个节点名 |
| **START / END** | 入口和出口 |
| **compile** | 编译成可执行对象,支持 `invoke` / `stream` / `ainvoke` / `astream`;传入 `checkpointer` 后支持持久化(下一课) |
为什么不直接写 while 循环?手写循环(第 10 周)能帮你理解原理;但当流程有分支、并行、人工审批、失败续跑时,LangGraph 把**状态保存、恢复、流式事件、可视化**都提供好了。
### 流式输出的几种模式
| `stream_mode` | 输出内容 | 用途 |
| --- | --- | --- |
| `"values"` | 每一步之后的完整状态 | 调试 |
| `"updates"` | 每个节点返回的更新 | 前端展示“当前在哪一步” |
| `"messages"` | 大模型逐 token 输出 | 打字机效果 |
| `"custom"` | 节点里用 `get_stream_writer()` 主动发送的任意数据 | 进度条、中间结果 |
可以同时订阅多种:`stream_mode=["updates", "custom"]`,返回 `(模式, 数据)` 元组。后端把这些事件转成 SSE 发给前端,就实现了“AI 原生”界面里的流式输出 + 任务进度。
## 案例
工单处理流程:分类 → 起草回复 → 金额大的退款需要人工审批 → 发送。分类结果用 pydantic 校验(结构化输出),不合法时走“转人工”分支;前端订阅 `custom` 流显示“正在分类 / 正在起草 / 等待审批”。
## 代码示例
最小的条件路由图(可直接运行):
```python
import operator
from typing import Annotated, TypedDict
from langgraph.graph import END, START, StateGraph
class State(TypedDict):
question: str
route: str
answer: str
steps: Annotated[list[str], operator.add] # 追加而不是覆盖
def route(state: State):
r = "billing" if "发票" in state["question"] else "general"
return {"route": r, "steps": [f"route:{r}"]}
def billing(state: State):
return {"answer": "开票请在订单详情页申请。", "steps": ["billing"]}
def general(state: State):
return {"answer": "已转给客服。", "steps": ["general"]}
g = StateGraph(State)
g.add_node("route", route)
g.add_node("billing", billing)
g.add_node("general", general)
g.add_edge(START, "route")
g.add_conditional_edges("route", lambda s: s["route"], ["billing", "general"])
g.add_edge("billing", END)
g.add_edge("general", END)
app = g.compile()
for update in app.stream({"question": "怎么开发票", "steps": []}, stream_mode="updates"):
print(update)
print(app.invoke({"question": "怎么开发票", "steps": []})["steps"]) # ['route:billing', 'billing']
```
完整的工单图(结构化输出校验、自动重试、人工审批、流式进度、崩溃续跑)见 [examples/ticket-flow](examples/ticket-flow/)。
## 易错点
- 节点返回了整个状态并修改了列表:应该只返回要更新的字段;列表字段要用 reducer 追加,不要原地 `append`。
- 条件边函数里修改状态:路由函数只负责返回下一个节点名,状态修改放在节点里。
- 条件边没有声明可能的目标(第三个参数),图的可视化和校验不完整。
- 图中有循环却没有退出条件:设置最大步数(`recursion_limit`,以及状态里自己的计数器)。
- 混用同步和异步:节点是 `async def` 时要用 `ainvoke` / `astream`。
## 面试常问
- LangGraph 和 LangChain 的关系?为什么需要 LangGraph?
- reducer 是什么?消息列表为什么用 `add_messages`?
- 怎么把图的执行过程流式推给前端?
+110
View File
@@ -0,0 +1,110 @@
---
id: ai.langgraph.persistence-hitl
title: 检查点、人机协作和异常恢复:checkpointer、interrupt、RetryPolicy、任务状态
type: lesson
domain: ai
stack: [langgraph]
tags: [checkpointer, thread_id, interrupt, Command, RetryPolicy, 崩溃恢复, 任务状态]
level: advanced
prerequisites: [ai.langgraph.state-graph]
est_hours: 4
related: [ai.langgraph.scenario.refund-approval, ai.agent-ops.eval-quality-gate, ai.langgraph.interview]
week: [12]
order: 2
---
# 检查点、人机协作和异常恢复:checkpointer、interrupt、RetryPolicy、任务状态
> 基于 langgraph 1.2 和 langgraph-checkpoint-sqlite 编写,以官方文档为准:https://docs.langchain.com/oss/python/langgraph/persistence
## 解释说明
### 检查点(checkpointer)
编译时传入 `checkpointer`,每执行完一步(super-step)就把状态保存下来,按 `thread_id` 区分不同的会话 / 任务:
| 实现 | 用途 |
| --- | --- |
| `InMemorySaver` | 测试、演示;进程退出就没了 |
| `SqliteSaver`(`langgraph-checkpoint-sqlite`) | 本地、单机 |
| `PostgresSaver`(`langgraph-checkpoint-postgres`) | 生产 |
有了检查点就能:多轮对话记住上下文、**进程崩溃后从最近的检查点继续**(`invoke(None, config)`)、查看历史状态(`get_state_history`)、人工审批后继续。
### 人机协作(interrupt)
节点里调用 `interrupt(要给人看的数据)`,图会暂停并保存状态;人处理完后调用 `invoke(Command(resume=人的决定), config)` 继续,`interrupt()` 的返回值就是人的决定。
注意:恢复时**这个节点会从头重新执行**,`interrupt()` 之前的代码会再跑一次,所以那里不要放发邮件、扣款这类副作用操作。
### 异常恢复
| 问题 | 做法 |
| --- | --- |
| 模型超时、限流(临时错误) | 节点级 `RetryPolicy(max_attempts=3, retry_on=...)` 自动重试,带退避 |
| 重试仍失败 / 进程崩溃 | 已完成节点的结果在检查点中;修复后 `invoke(None, config)` 从失败节点继续 |
| 外部副作用(发送、扣款)可能重复 | 用业务 ID 做**幂等键**,重复执行也只生效一次 |
| 结构化输出不合法 | pydantic 校验,失败时重试一次或进入“转人工”分支,不让整个流程崩掉 |
### 任务状态
长任务要有明确的状态字段,前端和运维都靠它:`new → classified → drafted / waiting_approval → approved / rejected → sent / failed`。状态写在图的 State 里,同时同步到业务表,方便列表页查询和告警(例如“等待审批超过 24 小时”)。
## 案例
退款工单:800 元的退款需要主管审批。流程在审批节点暂停,主管第二天在后台点“同意”,服务已经重启过,但因为检查点存在 SQLite / PostgreSQL 中,用同一个 `thread_id` 就能继续;发送时进程崩溃,恢复后不会重新起草、也不会重复发送。
## 代码示例
核心片段(完整可运行版本 [examples/ticket-flow/ticket_flow.py](examples/ticket-flow/ticket_flow.py),带 pytest 测试):
```python
from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.types import Command, RetryPolicy, interrupt
def approve(state):
# 恢复时本节点从头执行:interrupt 之前不要有副作用
decision = interrupt({"ticket_id": state["ticket_id"], "draft": state["draft"]})
return {"status": "approved" if decision["ok"] else "rejected"}
g.add_node("draft", draft, retry_policy=RetryPolicy(max_attempts=3, retry_on=TransientError))
g.add_node("approve", approve)
cfg = {"configurable": {"thread_id": "T-1001"}}
with SqliteSaver.from_conn_string("checkpoints.sqlite") as cp:
app = g.compile(checkpointer=cp)
app.invoke(ticket, cfg) # 停在 approve
print(app.get_state(cfg).next) # ('approve',)
# ……服务重启后……
with SqliteSaver.from_conn_string("checkpoints.sqlite") as cp:
app = g.compile(checkpointer=cp)
app.invoke(Command(resume={"ok": True}), cfg) # 继续执行审批之后的节点
app.invoke(None, cfg) # 如果中途崩溃,从最近的检查点继续
```
示例运行输出(节选):
```text
等待节点: ('approve',) 状态: waiting_approval
发送时崩溃: 进程崩溃(模拟)
崩溃后停在: ('send',) 状态: approved
最终状态: sent 事件: ['classified:refund', 'drafted', 'approved', 'sent']
```
## 易错点
- 没有传 `thread_id`:有检查点的图调用时必须提供,否则报错或者所有请求共享状态。
- 用 `InMemorySaver` 上生产:重启后所有进行中的任务丢失。
- `interrupt()` 之前做了副作用,恢复时重复执行。
- 恢复时传了新的输入而不是 `Command(resume=...)` 或 `None`:会被当成新的一轮输入。
- 重试所有异常:参数错误、权限错误重试没有意义,只重试临时错误。
- 状态里放了大对象(整篇文档、二进制):每一步都要序列化保存,检查点表迅速膨胀。放 ID,内容存在别处。
## 面试常问
- 检查点保存的是什么?什么时候保存?
- interrupt 恢复时为什么节点会重新执行?会带来什么问题?
- Agent 执行到一半服务重启了,怎么保证任务不丢、不重复?
@@ -0,0 +1,51 @@
# requires: langgraph, pydantic, pytest
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command
from ticket_flow import FakeLLM, Mailer, build
def run(text, llm=None, mailer=None, tid="t"):
llm, mailer = llm or FakeLLM(), mailer or Mailer()
app = build(llm, mailer, InMemorySaver())
cfg = {"configurable": {"thread_id": tid}}
out = app.invoke({"ticket_id": tid, "text": text, "status": "new", "events": []}, cfg)
return app, cfg, out, llm, mailer
def test_small_refund_sent_without_approval():
_, _, out, _, mailer = run("申请退款 30 元")
assert out["status"] == "sent" and "t" in mailer.sent
def test_large_refund_waits_then_rejected():
app, cfg, _, _, mailer = run("申请退款 900 元")
assert app.get_state(cfg).next == ("approve",)
out = app.invoke(Command(resume={"ok": False, "note": "超过权限"}), cfg)
assert out["status"] == "rejected" and not mailer.sent
def test_transient_error_retried():
_, _, out, llm, _ = run("系统报错 500", llm=FakeLLM(fail_times=2))
assert out["status"] == "sent" and llm.calls == 3
def test_retry_exhausted_raises_and_can_resume():
llm = FakeLLM(fail_times=3)
app = build(llm, Mailer(), InMemorySaver())
cfg = {"configurable": {"thread_id": "x"}}
try:
app.invoke({"ticket_id": "x", "text": "怎么开发票", "status": "new", "events": []}, cfg)
raise AssertionError("应该抛出异常")
except Exception as e:
assert "超时" in str(e)
assert app.get_state(cfg).next == ("draft",) # 停在失败的节点,分类结果保留
out = app.invoke(None, cfg) # 故障恢复后续跑
assert out["status"] == "sent" and out["events"].count("classified:question") == 1
def test_send_is_idempotent():
mailer = Mailer()
mailer.send("a", "x")
mailer.send("a", "y")
assert mailer.sent == {"a": "x"}
@@ -0,0 +1,178 @@
# requires: langgraph, pydantic
"""工单处理图:结构化分类 → 起草回复(失败自动重试)→ 高风险人工审批(interrupt)→ 发送(幂等)。
演示:任务状态字段、流式进度(custom 流)、检查点续跑(SqliteSaver)、人机协作、异常恢复。
不调用真实大模型:classify / draft 用规则模拟,接口形状和真实做法一致。
运行:python ticket_flow.py
基于 langgraph 1.2 编写,API 以官方文档为准:https://docs.langchain.com/oss/python/langgraph/overview
"""
from __future__ import annotations
import operator
import os
import re
import tempfile
from typing import Annotated, Literal, TypedDict
from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.config import get_stream_writer
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, RetryPolicy, interrupt
from pydantic import BaseModel, Field, ValidationError
Status = Literal["new", "classified", "drafted", "waiting_approval", "approved", "rejected", "sent", "failed"]
class Triage(BaseModel):
"""分类结果:真实项目里是大模型的结构化输出,这里用 pydantic 校验它。"""
category: Literal["refund", "bug", "question"]
amount: float = Field(ge=0, default=0)
urgent: bool = False
class TicketState(TypedDict, total=False):
ticket_id: str
text: str
triage: dict
draft: str
status: Status
reviewer_note: str
events: Annotated[list[str], operator.add] # 追加式字段:每个节点追加一条,作为审计记录
class TransientError(Exception):
"""可重试的错误:超时、限流、5xx。"""
# ---------- 外部依赖(测试里可以替换) ----------
class FakeLLM:
def __init__(self, fail_times: int = 0):
self.fail_times = fail_times
self.calls = 0
def classify(self, text: str) -> str:
# 真实模型返回 JSON 字符串;这里也返回字符串,交给 pydantic 校验
if "退款" in text:
m = re.search(r"(\d+(?:\.\d+)?)\s*元", text)
amount = float(m.group(1)) if m else 0
return f'{{"category": "refund", "amount": {amount}, "urgent": {str("加急" in text).lower()}}}'
if "报错" in text:
return '{"category": "bug", "urgent": true}'
return '{"category": "question"}'
def draft(self, text: str, triage: Triage) -> str:
self.calls += 1
if self.calls <= self.fail_times:
raise TransientError("模型接口超时")
return f"[{triage.category}] 您好,关于“{text}”,我们已经处理,请留意通知。"
class Mailer:
"""发送通道。用 ticket_id 做幂等键:同一个工单重复执行也只发一次。"""
def __init__(self, crash_once: bool = False):
self.sent: dict[str, str] = {}
self.crash_once = crash_once
def send(self, ticket_id: str, body: str) -> None:
if ticket_id in self.sent:
return
if self.crash_once:
self.crash_once = False
raise RuntimeError("进程崩溃(模拟)")
self.sent[ticket_id] = body
APPROVAL_AMOUNT = 500
def needs_approval(triage: dict) -> bool:
return triage["category"] == "refund" and triage["amount"] >= APPROVAL_AMOUNT
def build(llm: FakeLLM, mailer: Mailer, checkpointer):
def classify(state: TicketState):
get_stream_writer()({"step": "classify", "msg": "正在分类"})
raw = llm.classify(state["text"])
try:
triage = Triage.model_validate_json(raw)
except ValidationError as e: # 结构化输出不合法:降级为人工处理,而不是让流程崩掉
return {"status": "failed", "events": [f"classify_invalid:{e.error_count()}"]}
return {"triage": triage.model_dump(), "status": "classified", "events": [f"classified:{triage.category}"]}
def draft(state: TicketState):
get_stream_writer()({"step": "draft", "msg": "正在起草回复"})
text = llm.draft(state["text"], Triage(**state["triage"]))
status = "waiting_approval" if needs_approval(state["triage"]) else "drafted"
return {"draft": text, "status": status, "events": ["drafted"]}
def need_approval(state: TicketState) -> str: # 条件边只做路由,不修改状态
return "approve" if needs_approval(state["triage"]) else "send"
def approve(state: TicketState):
# interrupt 之前的代码在恢复时会重新执行一次,所以这里不要放有副作用的操作
decision = interrupt({"ticket_id": state["ticket_id"], "draft": state["draft"],
"amount": state["triage"]["amount"]})
if decision.get("ok"):
return {"status": "approved", "reviewer_note": decision.get("note", ""), "events": ["approved"]}
return {"status": "rejected", "reviewer_note": decision.get("note", ""), "events": ["rejected"]}
def after_approve(state: TicketState) -> str:
return "send" if state["status"] == "approved" else END
def send(state: TicketState):
get_stream_writer()({"step": "send", "msg": "正在发送"})
mailer.send(state["ticket_id"], state["draft"])
return {"status": "sent", "events": ["sent"]}
g = StateGraph(TicketState)
g.add_node("classify", classify)
g.add_node("draft", draft, retry_policy=RetryPolicy(max_attempts=3, initial_interval=0.01,
retry_on=TransientError))
g.add_node("approve", approve)
g.add_node("send", send)
g.add_edge(START, "classify")
g.add_conditional_edges("classify", lambda s: END if s["status"] == "failed" else "draft")
g.add_conditional_edges("draft", need_approval, ["approve", "send"])
g.add_conditional_edges("approve", after_approve, ["send", END])
g.add_edge("send", END)
return g.compile(checkpointer=checkpointer)
def main() -> None:
db = os.path.join(tempfile.mkdtemp(), "checkpoints.sqlite")
llm, mailer = FakeLLM(fail_times=1), Mailer(crash_once=True)
cfg = {"configurable": {"thread_id": "T-1001"}}
ticket = {"ticket_id": "T-1001", "text": "订单 A1 申请退款 800 元", "status": "new", "events": []}
# 第一次运行:draft 第一次超时被自动重试;遇到 800 元退款,停在人工审批
with SqliteSaver.from_conn_string(db) as cp:
app = build(llm, mailer, cp)
for mode, chunk in app.stream(ticket, cfg, stream_mode=["custom", "updates"]):
if mode == "custom":
print("进度:", chunk["msg"])
snap = app.get_state(cfg)
print("等待节点:", snap.next, "状态:", snap.values["status"])
assert snap.values["status"] == "waiting_approval" and snap.values["triage"]["amount"] == 800
print("待审批内容:", snap.tasks[0].interrupts[0].value)
assert snap.next == ("approve",) and llm.calls == 2
# 审批人第二天才处理:新的进程、新的图对象,只要 thread_id 一样就能接着跑
with SqliteSaver.from_conn_string(db) as cp:
app = build(llm, mailer, cp)
try:
app.invoke(Command(resume={"ok": True, "note": "金额核对无误"}), cfg)
except RuntimeError as e:
print("发送时崩溃:", e)
snap = app.get_state(cfg)
print("崩溃后停在:", snap.next, "状态:", snap.values["status"])
# 崩溃恢复:传 None 表示从最近的检查点继续,已经完成的节点(起草、审批)不会重新执行
with SqliteSaver.from_conn_string(db) as cp:
app = build(llm, mailer, cp)
final = app.invoke(None, cfg)
print("最终状态:", final["status"], "事件:", final["events"])
assert final["status"] == "sent" and llm.calls == 2 and "T-1001" in mailer.sent
if __name__ == "__main__":
main()
+32 -3
View File
@@ -4,12 +4,41 @@ title: LangGraph
type: index
domain: ai
stack: [langgraph]
tags: []
tags: [LangGraph, 状态图, 检查点, 人机协作]
week: [11, 12]
---
# LangGraph
状态图、条件路由、检查点续跑、interrupt、长期记忆。
用有状态的图编排 Agent。岗位要求里的“工作流编排、多 Agent、人工介入、任务状态、异常恢复”基本都落在这里。先在第 10 周手写工具调用循环,再用 LangGraph 重写。
> 本专题建设中:课程、企业场景、面试题和示例代码会陆续补充。
## 学习路线
| 顺序 | 课程 | 级别 | 预计 |
| --- | --- | --- | --- |
| 1 | [LangGraph 状态图:状态、节点、边、条件路由和流式输出](01-state-graph.md) | 进阶 | 3 小时 |
| 2 | [检查点、人机协作和异常恢复:checkpointer、interrupt、RetryPolicy、任务状态](02-persistence-hitl.md) | 高级 | 4 小时 |
## 企业场景
- [退款工单 Agent:人工审批、任务状态和崩溃恢复](scenarios/refund-approval.md)
## 面试题
- [LangGraph 面试题](interview.md)
## 示例代码
- [examples/ticket-flow](examples/ticket-flow/):工单处理图——pydantic 校验结构化输出、`RetryPolicy` 重试、`interrupt` 人工审批、`custom` 流式进度、`SqliteSaver` 崩溃续跑、幂等发送;带 pytest 测试(需要 `langgraph`、`langgraph-checkpoint-sqlite`、`pydantic`)
## 在 16 周计划中
- [第 11 周:LangGraph 多 Agent 编排](../../../plan/week11-agent-m2-langgraph.md)、[第 12 周:持久化和人机协作](../../../plan/week12-agent-m3-persistence.md)
## 官方资料
LangGraph 更新很快,以官方文档为准:
- https://docs.langchain.com/oss/python/langgraph/overview
- 持久化:https://docs.langchain.com/oss/python/langgraph/persistence
- 人机协作:https://docs.langchain.com/oss/python/langgraph/interrupts
+67
View File
@@ -0,0 +1,67 @@
---
id: ai.langgraph.interview
title: LangGraph 面试题
type: interview
domain: ai
stack: [langgraph]
tags: [LangGraph, 检查点, 人机协作, 面试]
level: intermediate
related: [ai.langgraph.state-graph, ai.langgraph.persistence-hitl]
week: [11, 12, 16]
---
# LangGraph 面试题
## 基础
### 【基础】LangGraph 解决什么问题?和 LangChain 是什么关系?
**参考答案**:LangGraph 用有状态的图来编排 Agent 和工作流,提供状态管理、条件分支、循环、检查点持久化、人工介入、流式事件。LangChain 提供模型、消息、工具等组件,LangChain 1.x 的 `create_agent` 底层也是基于 LangGraph 构建的。简单的单次调用用 LangChain 即可,复杂流程用 LangGraph。
**追问**:不用框架能做吗?→ 能,手写循环 + 状态表也可以;框架的价值是现成的持久化、恢复和事件流,代价是学习成本和版本变化。
### 【基础】State 和 reducer 是什么?
**参考答案**:State 是所有节点共享的数据结构,节点返回部分更新;reducer 决定某个字段如何合并,默认覆盖,列表可以用 `operator.add` 追加,消息用 `add_messages`(按 id 追加或替换)。
**追问**:两个并行节点同时更新一个没有 reducer 的字段会怎样?→ 会报错(同一步内多个更新冲突),需要给该字段定义 reducer。
### 【基础】`stream_mode` 有哪些?
**参考答案**:`values`(完整状态)、`updates`(节点的增量更新)、`messages`(大模型 token 流)、`custom`(节点主动发出的自定义事件)等,可以同时订阅多种。
**追问**:前端怎么拿到这些事件?→ 后端遍历 `astream` 的结果,转成 SSE 事件发送,前端按事件类型渲染进度和文本。
## 进阶
### 【进阶】checkpointer 保存了什么?有什么用?
**参考答案**:每一步执行后保存的状态快照、下一步要执行的节点、待处理的中断等,按 `thread_id` 组织。用途:多轮对话记忆、人工审批暂停 / 恢复、崩溃后续跑、查看历史和回溯(time travel)。
**追问**:生产环境用什么?→ PostgreSQL 等持久化实现;要考虑检查点表的增长和定期清理。
### 【进阶】interrupt 的工作原理和注意事项?
**参考答案**:节点中调用 `interrupt(value)` 会抛出特殊信号,图暂停并保存状态,`value` 返回给调用方;调用 `Command(resume=x)` 后,该节点从头重新执行,这一次 `interrupt()` 返回 x。注意 interrupt 之前的代码会重复执行,不能有副作用;一个节点里多个 interrupt 按顺序匹配 resume 值。
**追问**:需要用户修改 Agent 生成的参数后再执行,怎么做?→ interrupt 返回用户编辑后的参数,节点用新参数执行工具调用。
### 【进阶】Agent 执行中服务崩溃了,怎么恢复?
**参考答案**:有检查点时,用同一个 `thread_id` 调用 `invoke(None, config)` 从最近的检查点继续;已完成节点不会重新执行,但崩溃时正在执行的节点会重新执行,所以有副作用的节点要幂等。多实例部署时用租约避免重复恢复。
**追问**:怎么发现“卡住”的任务?→ 业务表记录状态和更新时间,定时任务扫描长时间未更新的任务并告警或自动恢复。
## 场景题
### 【场景题】设计一个需要人工审批的退款 Agent。
**参考答案**:分类(结构化输出校验)→ 起草(重试临时错误)→ 金额超过阈值时 interrupt 等待审批 → 执行退款(幂等键)→ 通知。检查点存 PostgreSQL,thread_id 为工单号;状态同步到业务表;审批接口校验当前状态和审批权限;SSE 推送进度。详见[退款工单场景](scenarios/refund-approval.md)。
**追问**:审批超时怎么办?→ 定时任务检查等待时间,提醒或升级给上级;超过期限自动拒绝并通知用户。
### 【场景题】Agent 偶尔陷入循环,反复调用同一个工具,怎么处理?
**参考答案**:设置 `recursion_limit` 和状态里的步数计数器,达到上限后结束并返回已有结果或转人工;检测重复的工具调用(同名同参数)并提示模型换方法;在评测集中加入这类用例,分析是提示词、工具描述还是工具返回信息不足导致的。
**追问**:怎么在线上发现这类问题?→ 记录每次运行的步数和工具调用序列,监控步数分布和超过上限的比例。
@@ -0,0 +1,86 @@
---
id: ai.langgraph.scenario.refund-approval
title: 退款工单 Agent:人工审批、任务状态和崩溃恢复
type: scenario
domain: ai
stack: [langgraph, fastapi, postgresql]
tags: [人机协作, 审批流, 任务状态, 异常恢复, 幂等, 流式进度]
level: advanced
prerequisites: [ai.langgraph.persistence-hitl]
est_hours: 3
related: [ai.langgraph.interview, ai.agent-ops.scenario.agent-quality-gate, backend.postgresql.scenario.order-state-audit]
week: [12]
---
# 退款工单 Agent:人工审批、任务状态和崩溃恢复
## 业务背景与问题
客服系统接入 Agent 自动处理退款工单:识别工单类型和金额、查询订单、起草回复、执行退款。试运行发现:
1. 大额退款不能让 Agent 直接执行,需要主管审批,审批可能隔天才处理;
2. 模型接口偶尔超时,整个工单就失败了,要客服手动重新提交;
3. 一次发版重启,几十个“处理中”的工单状态卡住,不知道执行到哪一步;
4. 有工单重复退款了两次;
5. 客服页面只显示“处理中”,不知道 Agent 在做什么。
## 约束
- 审批阈值:500 元及以上需要人工审批。
- 退款接口是第三方支付接口,支持幂等键。
- 服务多实例部署,可能随时重启。
## 方案设计
```mermaid
flowchart LR
A[分类<br/>结构化输出校验] -->|不合法| H[转人工]
A --> B[起草回复<br/>RetryPolicy 重试]
B -->|小额| D[执行退款 + 发送<br/>幂等键=工单号]
B -->|大额| C[interrupt 等待审批]
C -->|同意| D
C -->|拒绝| E[结束]
```
1. **LangGraph + PostgresSaver**:每一步保存检查点,`thread_id = 工单号`。
2. **审批**:审批节点调用 `interrupt`,同时把工单状态改为 `waiting_approval` 写入业务表;主管在后台点击后,接口调用 `Command(resume=...)` 继续。
3. **临时错误**:模型调用节点配置 `RetryPolicy`,只重试超时 / 限流 / 5xx。
4. **崩溃恢复**:后台巡检任务定期找出状态是“处理中”但长时间没有更新的工单,用 `invoke(None, config)` 从检查点继续(多实例下要先抢占租约,避免两个实例同时恢复同一个工单)。
5. **幂等**:退款和发送都用工单号做幂等键;状态更新用条件更新(`WHERE status = ...`)。
6. **流式进度**:节点里用 `get_stream_writer()` 发送进度,接口转成 SSE 推给客服页面。
## 关键代码
完整可运行示例:[examples/ticket-flow](../examples/ticket-flow/)。审批接口(FastAPI,示意):
```python
@app.post("/tickets/{ticket_id}/approval")
async def approve(ticket_id: str, body: ApprovalIn, user=Depends(require_role("supervisor"))):
cfg = {"configurable": {"thread_id": ticket_id}}
snap = await graph.aget_state(cfg)
if snap.next != ("approve",):
raise HTTPException(409, "工单不在待审批状态")
await graph.ainvoke(Command(resume={"ok": body.ok, "note": body.note, "by": user.id}), cfg)
return {"status": (await graph.aget_state(cfg)).values["status"]}
```
## 取舍
| 选择 | 优点 | 缺点 |
| --- | --- | --- |
| **LangGraph 检查点(本方案)** | 自带暂停 / 恢复 / 历史,代码少 | 依赖框架;检查点表需要清理 |
| 自己用状态机 + 任务表实现 | 完全可控,和业务表一体 | 要自己实现恢复、重试、事件流 |
| 工作流引擎(Temporal 等) | 可靠性强,适合长流程 | 学习和运维成本高 |
| 全部人工审批 | 最安全 | 失去自动化的意义;用阈值和抽检平衡 |
## 易错点
- 审批节点在 `interrupt` 之前就执行了退款。
- 检查点和业务表的状态不一致:以业务表为准对账,或者在同一个节点里同时更新。
- 恢复任务没有租约,多实例同时恢复同一个工单。
- 审批接口没有校验当前状态,重复点击导致重复恢复。
- 审批人看不到 Agent 的依据:审批数据要包含订单信息、起草内容、分类结果。
## 面试怎么讲
> “退款 Agent 我用 LangGraph 做,检查点存在 PostgreSQL,thread_id 就是工单号。大额退款在审批节点 interrupt,状态写成待审批,主管点同意后用 Command resume 继续。模型超时用节点级重试;服务重启后巡检任务抢到租约,再从检查点续跑,已经完成的步骤不会重复执行;退款接口用工单号做幂等键,防止重复退款。前端通过 SSE 看到每一步的进度。”