LangGraph实战：打造你的AI“项目经理”！一个会“暂停思考”的Planner有多强？

最新推荐文章于 2025-11-30 18:24:05 发布

原创最新推荐文章于 2025-11-30 18:24:05 发布 · 745 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能 #算法 #sql #oracle #数据库

要让一个写作 Agent 真正可控、可信，仅靠“问一句答一句”远远不够。

整体架构

一、规划阶段：Planner 既聪明又稳妥

1.结构化规划优先，失败兜底

我们让 Planner 通过结构化 LLM 输出步骤（含标题、执行说明、是否需要确认、建议工具）。如果解析失败，就落回预置的四步模版，并在消息中提示 [warning]，避免系统陷入未知状态。

建议的 Step 结构（示例 JSON Schema）：

{
"steps": [
{
"id": "step-001",
"title": "确认文章标题",
"instruction": "给出3个备选标题并说明理由",
"requires_confirmation": true,
"suggested_tools": ["title_generator"]
}
]
}

Pydantic/TypedDict（后端强约束）：

class PlanStepState(TypedDict, total=False):
id: str
title: str
description: str
requires_confirmation: bool
tool_names: List[str]
status: StepStatus
result: str
confirmed: bool
result_message_id: Optional[str]
prepared_instruction: str
class AgentState(TypedDict, total=False):
messages: Annotated[List[AnyMessage], add_messages]
plan: List[PlanStepState]
current_step: int
status: str
pending_interrupt: Optional[Dict[str, Any]]
active_step_id: Optional[str]
last_step_update: Optional[Dict[str, Any]]
FALLBACK_PLAN_BLUEPRINT: List[Dict[str, Any]] = [
{
"title": "确认文章标题与角度",
"description": "根据用户需求列出 1-2 个备选标题，请用户确认后再继续。",
"requires_confirmation": True,
"tool_names": ["faq"],
},
{
"title": "资料调研与要点整理",
"description": "利用 multi_search 或 kb_search 收集 LangGraph 最新进展与核心卖点，沉淀出 3-4 条写作提纲。",
"tool_names": ["multi_search", "kb_search"],
},
{
"title": "撰写正文草稿",
"description": "围绕确认后的标题与提纲，生成公众号风格正文（含小标题、数据或案例引用）。",
"tool_names": [],
},
{
"title": "校对与发布建议",
"description": "检查稿件逻辑、润色语言，并给出排版与配图提示。",
"tool_names": [],
},
]

解析与兜底：

def planner(state: AgentState) -> AgentState:
messages = state.get("messages", [])
goal = _extract_user_goal(messages)
if not goal:
return {"status": "waiting_for_input"}
outline: Optional[PlanOutline]
planner_note: Optional[str] = None
try:
outline = planner_llm.invoke(
[
SystemMessage(content=PLANNER_PROMPT),
HumanMessage(content=goal),
]
)
except Exception as exc:  # pragma: no cover - fallback only
logger.warning("Planner structured output failed: %s", exc)
planner_note = "Planner output could not be parsed; switched to a default four-step template."
objective = goal or "default objective"
fallback_steps = [
PlanStepModel(**step_blueprint) for step_blueprint in FALLBACK_PLAN_BLUEPRINT
]
outline = PlanOutline(objective=objective, steps=fallback_steps[:4])

2.首步确认可配置

像“先确认标题”这类需求，只需在步骤里标 requires_confirmation=true，即可触发中断等待操作；后续也可按场景扩展需要确认的节点。

二、执行阶段：Executor 执行步骤 + 中断控制

1.状态机设计：

Executor 会把每一步的状态从 pending → waiting → in_progress → completed 演进，确保可观测与可回溯。

StepStatus = Literal[
"pending",
"waiting",
"in_progress",
"completed",
"cancelled",
"failed",
]

遇到确认点立即中断：当步骤需确认时，Executor 会写入 pending_interrupt 并通过 NodeInterrupt 抛出中断，让流程停在前端弹窗。反之，则构造明确的执行指令继续推进。

关键细节：我们特意让 interrupt_gate 在无中断时返回 {“pending_interrupt”: None}，防止恢复阶段出现空写异常。

def interrupt_gate(state: AgentState) -> AgentState:
pending = state.get("pending_interrupt")
if pending:
logger.info(
"interrupt_gate raising interrupt for step=%s",
pending.get("step_id") if isinstance(pending, dict) else pending,
)
raise NodeInterrupt(pending)
return {"pending_interrupt": None}

三、恢复与复盘：/chat/continue + Step Reporter

1./chat/continue：一次性写回“正确字段”

前端点击「继续」后，/chat/continue 会把 plan / status / pending_interrupt / active_step_id / last_step_update / messages 等字段一次写回，既提醒下一步该干什么，也避免 InvalidUpdateError。

2.Step Reporter 双向同步

每当 Executor 完成某一步，step_reporter 会更新步骤状态、保存结果，并推送一个新的 AI 消息。前端既能在看板上看到该步骤“完成”，又能在聊天区看见标有 STEP RESULT 标签的阶段产出。

def step_reporter(state: AgentState) -> AgentState:
plan = _clone_plan(state.get("plan", []))
idx = state.get("current_step", 0)
if not plan or idx >= len(plan):
logger.debug("step_reporter nothing to report idx=%s total=%s", idx, len(plan))
return {
"plan": plan,
"status": "completed" if plan else "idle",
"active_step_id": None,
"pending_interrupt": None,
}
step = plan[idx]
if step.get("status") != "in_progress":
logger.debug(
"step_reporter skip step=%s status=%s",
step.get("id"),
step.get("status"),
)
return {}
exclude = {step.get("result_message_id")} if step.get("result_message_id") else set()
latest_ai = _find_latest_ai_message(state.get("messages", []), exclude)
if not latest_ai:
logger.debug("step_reporter no new ai message for step=%s", step.get("id"))
return {}
if isinstance(latest_ai.content, str):
result_text = latest_ai.content
else:
result_text = json.dumps(latest_ai.content, ensure_ascii=False)
step["status"] = "completed"
step["result"] = result_text
step["result_message_id"] = latest_ai.id
plan[idx] = step
next_idx = idx + 1
updates: AgentState = {
"plan": plan,
"current_step": next_idx,
"pending_interrupt": None,
"active_step_id": plan[next_idx]["id"] if next_idx < len(plan) else None,
"status": "completed" if next_idx >= len(plan) else "executing",
"last_step_update": {
"step_id": step["id"],
"status": "completed",
"result": step.get("result", ""),
},
# "messages":[latest_ai],
}
logger.info(
"step_reporter completed step=%s next_idx=%s result=%s",
step["id"],
next_idx,
step.get("result", ""),
)
return updates

四、踩过的坑 & 解决方案

1、NodeInterrupt 无法序列化 → SSE 报错

处理：utils._to_serializable 将中断对象转为普通 dict，并在 无中断 时显式写回 pending_interrupt=None。

2、InvalidUpdateError（恢复时）

处理：/chat/continue 一次性写回 白名单字段；恢复前先清空/占位 pending_interrupt。

3、工具超时/挂起

处理：全局超时 + 重试 + 降级策略；记录错误上下文，保证流程可继续。

4、步骤字段不完整

处理：Planner 解析前后各做一次 schema 校验；失败即兜底模板并写入 [warning]。

实操演示

以“写一篇关于 LangGraph 的公众号文章”为例：

1、Planner 拆解

自动输出 5 个步骤：确认标题 → 收集材料 → 构建大纲 → 撰写正文 → 复盘优化，其中第 1 步标记需确认。

2、等待确认

Executor 停在标题确认流程，弹窗提示；前端 Steps 显示状态为 “Waiting for confirmation”。

3、继续执行

点击 “继续” 后，后端写回状态；Executor 切换到 in_progress，同时向 AI 发送具体执行提示。

4、阶段产出

每步完成后，步骤卡片与聊天窗口同步出现结果（带 STEP RESULT 标签），方便边看边调。

5、流程结束

当所有步骤完成时，状态标签变为 “COMPLETED”，提示可以发起新任务；整个执行过程既留档又透明。

总结

通过可中断的 Planner、状态可感知的 Executor、和信息可视化的Step Reporter，我们把写作流程拆成可预测、可回溯、可控制的流水线。

重要节点 先确认再执行，
工具调用 可仲裁、可并行、可降级，
阶段产出 双通道同步（看板 + 聊天）

既适合个人写作委托，也方便团队协作与复盘。如果你也想把自己的领域流程搬到 LangGraph 上，这套“项目经理级 Agent”就是一个即插即用的骨架。

想要完整代码 github下载

git clone -b third --single-branch git@github.com:xywang279/langgraph.git

如何学习大模型 AI ？

由于新岗位的生产效率，要优于被取代岗位的生产效率，所以实际上整个社会的生产效率是提升的。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑，所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限，很多互联网行业朋友无法获得正确的资料得到学习提升，故此将并将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

在这里插入图片描述