中断 - Docs by LangChain中文

中断允许您在图执行的特定点暂停，并在继续之前等待外部输入。这实现了“人在回路”的模式，适用于需要外部输入才能继续执行的场景。当中断被触发时，LangGraph 会使用其持久化层保存图的状态，并无限期等待，直到您恢复执行。中断通过在您图的节点中的任何位置调用 interrupt() 函数来工作。该函数接受任何 JSON 可序列化的值，该值会暴露给调用者。当您准备好继续执行时，通过使用 Command 重新调用图来恢复执行，然后 Command 中的值就成为节点内部 interrupt() 调用的返回值。与静态断点（在特定节点之前或之后暂停）不同，中断是动态的：它们可以放置在代码中的任何位置，并且可以根据您的应用逻辑设置为有条件的。

检查点保留您的进度： 检查点器会写入精确的图状态，因此您稍后可以恢复，即使处于错误状态时也是如此。
thread_id 是您的指针： 使用 { configurable: { thread_id: ... } } 作为 invoke 方法的选项，以告知检查点器要加载哪个状态。
中断载荷作为 __interrupt__ 暴露： 您传递给 interrupt() 的值会通过 __interrupt__ 字段返回给调用者，这样您就能知道图在等待什么。

您选择的 thread_id 实际上就是您的持久化游标。重用它可以恢复到同一个检查点；使用新值则会启动一个全新的、具有空状态的线程。

使用 `interrupt` 暂停

interrupt 函数会暂停图的执行并返回一个值给调用者。当您在节点内调用 interrupt 时，LangGraph 会保存当前的图状态，并等待您用输入恢复执行。要使用 interrupt，您需要：

一个检查点器来持久化图的状态（在生产环境中使用持久化的检查点器）
在您的配置中设置一个线程 ID，以便运行时知道要从哪个状态恢复
在您想要暂停的地方调用 interrupt()（载荷必须是 JSON 可序列化的）

import { interrupt } from "@langchain/langgraph";

async function approvalNode(state: State) {
    // 暂停并请求批准
    const approved = interrupt("Do you approve this action?");

    // Command({ resume: ... }) 提供了返回到此变量的值
    return { approved };
}

当您调用 interrupt 时，会发生以下情况：

图的执行被挂起 在调用 interrupt 的确切位置
状态被保存 使用检查点器，以便稍后可以恢复执行。在生产环境中，这应该是持久化的检查点器（例如，由数据库支持）
值被返回 给调用者，通过 __interrupt__ 字段；它可以是任何 JSON 可序列化的值（字符串、对象、数组等）
图无限期等待 直到您用响应恢复执行
响应被传回 节点，当您恢复时，它成为 interrupt() 调用的返回值

恢复中断

在中断暂停执行后，您可以通过再次调用图并传递一个包含恢复值的 Command 来恢复图。该恢复值会被传回 interrupt 调用，允许节点使用外部输入继续执行。

import { Command } from "@langchain/langgraph";

// 初始运行 - 触及中断并暂停
// thread_id 是指向保存的检查点的持久化指针
const config = { configurable: { thread_id: "thread-1" } };
const result = await graph.invoke({ input: "data" }, config);

// 检查被中断的内容
// __interrupt__ 反映了您传递给 interrupt() 的每个载荷
console.log(result.__interrupt__);
// [{ value: 'Do you approve this action?', ... }]

// 使用人类的响应恢复
// Command({ resume }) 在节点中将该值从 interrupt() 返回
await graph.invoke(new Command({ resume: true }), config);

关于恢复的关键点：

恢复时必须使用与中断发生时相同的线程 ID
传递给 new Command({ resume: ... }) 的值会成为 interrupt 调用的返回值
节点在恢复时会从调用 interrupt 的节点开头重新开始运行，因此 interrupt 之前的任何代码都会再次运行
您可以传递任何 JSON 可序列化的值作为恢复值

new Command({ resume: ... }) 是唯一设计用于作为 invoke()/stream()/stream_events() 输入的 Command 模式。其他 Command 参数（update、goto、graph）是设计用于从节点函数返回的。不要传递 new Command({ update: ... }) 作为输入来继续多轮对话——而是传递一个普通的输入对象。

常见模式

中断解锁的关键能力是暂停执行并等待外部输入。这对于多种用例都很有用，包括：

审批工作流: 在执行关键操作（API 调用、数据库更改、金融交易）之前暂停
处理多个中断: 在单次调用中恢复多个中断时，将中断 ID 与恢复值配对
审查和编辑: 让人类在继续之前审查和修改 LLM 输出或工具调用
中断工具调用: 在执行工具调用之前暂停，以便在执行前审查和编辑工具调用
验证人类输入: 在继续下一步之前暂停，以验证人类输入

使用人在回路 (HITL) 中断进行流式处理

当构建具有人在回路工作流的交互式代理时，您可以使用事件流在处理中断的同时并发消费消息块和状态快照。使用 graph.stream_events(..., version="v3") 返回的类型化投影，循环处理直到运行完成：

通过 stream.messages 逐个标记地流式传输 AI 响应
通过 stream.values 观察每一步的状态快照
通过 stream.interrupted 检测中断，并从 stream.interrupts 读取其载荷
通过再次使用 Command(resume=...) 调用 stream_events 来恢复执行，并重复此过程直到 stream.interrupted 为 false

import { Command } from "@langchain/langgraph";

let streamInput: Record<string, unknown> | Command = initialInput;

while (true) {
  const stream = await graph.streamEvents(streamInput, {
    ...config,
    version: "v3",
  });

  // 流式传输 LLM 消息块（包括子图中的任何消息），并在它们到达时进行处理。
  for await (const message of stream.messages) {
    for await (const token of message.text) {
      displayStreamingContent(token);
    }
  }

  // 运行结束后（或暂停后），检查中断并恢复。
  if (!stream.interrupted) {
    const finalState = await stream.output;
    break;
  }

  const interruptInfo = stream.interrupts[0].payload;
  const userResponse = await getUserInput(interruptInfo);
  streamInput = new Command({ resume: userResponse });
}

stream.messages：聊天模型输出作为内容块；迭代 message.text 获取标记增量。对于嵌套子图，从 stream.subgraphs[*].messages 读取消息块。
stream.values：每步之后的完整状态快照
stream.interrupted / stream.interrupts：每次运行后，检查图是否暂停；从 stream.interrupts 读取载荷
Command(resume=...)：作为下一个 streamEvents 输入传递以恢复；循环直到运行完成而不中断

处理多个中断

当并行分支同时中断时（例如，扇出到多个节点，每个节点都调用 interrupt()），您可能需要在单次调用中恢复多个中断。当使用单次调用恢复多个中断时，将每个中断 ID 映射到其恢复值。这确保每个响应在运行时与正确的中断配对。

import {
  Annotation,
  Command,
  END,
  INTERRUPT,
  MemorySaver,
  START,
  StateGraph,
  interrupt,
  isInterrupted,
} from "@langchain/langgraph";

const State = Annotation.Root({
  vals: Annotation<string[]>({
    reducer: (left, right) =>
      left.concat(Array.isArray(right) ? right : [right]),
    default: () => [],
  }),
});

function nodeA(_state: typeof State.State) {
  const answer = interrupt("question_a") as string;
  return { vals: [`a:${answer}`] };
}

function nodeB(_state: typeof State.State) {
  const answer = interrupt("question_b") as string;
  return { vals: [`b:${answer}`] };
}

const graph = new StateGraph(State)
  .addNode("a", nodeA)
  .addNode("b", nodeB)
  .addEdge(START, "a")
  .addEdge(START, "b")
  .addEdge("a", END)
  .addEdge("b", END)
  .compile({ checkpointer: new MemorySaver() });

const config = { configurable: { thread_id: "1" } };

async function main() {
  // 步骤 1：调用 - 两个并行节点都遇到 interrupt() 并暂停
  const interruptedResult = await graph.invoke({ vals: [] }, config);
  console.log(interruptedResult);
  /*
  {
    vals: [],
    __interrupt__: [
      { id: '...', value: 'question_a' },
      { id: '...', value: 'question_b' }
    ]
  }
  */

  // 步骤 2：一次恢复所有待处理的中断
  const resumeMap: Record<string, string> = {};
  if (isInterrupted(interruptedResult)) {
    for (const i of interruptedResult[INTERRUPT]) {
      if (i.id != null) {
        resumeMap[i.id] = `answer for ${i.value}`;
      }
    }
  }
  const result = await graph.invoke(new Command({ resume: resumeMap }), config);

  console.log("Final state:", result);
  //> Final state: { vals: ['a:answer for question_a', 'b:answer for question_b'] }
}

main().catch(console.error);

批准或拒绝

中断最常见的用途之一是在关键操作之前暂停并请求批准。例如，您可能希望让人类批准一个 API 调用、数据库更改或任何其他重要决定。

import { interrupt, Command } from "@langchain/langgraph";

const approvalNode: typeof State.Node = (state) => {
  // 暂停执行；载荷出现在 result.__interrupt__ 中
  const isApproved = interrupt({
    question: "Do you want to proceed?",
    details: state.actionDetails
  });

  // 根据响应进行路由
  if (isApproved) {
    return new Command({ goto: "proceed" }); // 在提供恢复载荷后运行
  } else {
    return new Command({ goto: "cancel" });
  }
}

当您恢复图时，传递 true 以批准或 false 以拒绝：

// 要批准
await graph.invoke(new Command({ resume: true }), config);

// 要拒绝
await graph.invoke(new Command({ resume: false }), config);

完整示例

import {
  Command,
  MemorySaver,
  START,
  END,
  StateGraph,
  StateSchema,
  interrupt,
} from "@langchain/langgraph";
import * as z from "zod";

const State = new StateSchema({
  actionDetails: z.string(),
  status: z.enum(["pending", "approved", "rejected"]).nullable(),
});

const graphBuilder = new StateGraph(State)
  .addNode("approval", async (state) => {
    // 暴露详细信息以便调用者在 UI 中渲染它们
    const decision = interrupt({
      question: "Approve this action?",
      details: state.actionDetails,
    });
    return new Command({ goto: decision ? "proceed" : "cancel" });
  }, { ends: ['proceed', 'cancel'] })
  .addNode("proceed", () => ({ status: "approved" }))
  .addNode("cancel", () => ({ status: "rejected" }))
  .addEdge(START, "approval")
  .addEdge("proceed", END)
  .addEdge("cancel", END);

// 在生产环境中使用更持久的检查点器
const checkpointer = new MemorySaver();
const graph = graphBuilder.compile({ checkpointer });

const config = { configurable: { thread_id: "approval-123" } };
const initial = await graph.invoke(
  { actionDetails: "Transfer $500", status: "pending" },
  config,
);
console.log(initial.__interrupt__);
// [{ value: { question: ..., details: ... } }]

// 使用决定恢复；true 路由到 proceed，false 到 cancel
const resumed = await graph.invoke(new Command({ resume: true }), config);
console.log(resumed.status); // -> "approved"

审查和编辑状态

有时您希望让人类在继续之前审查并编辑部分图状态。这对于纠正 LLM、添加缺失信息或进行调整很有用。

import { interrupt } from "@langchain/langgraph";

const reviewNode: typeof State.Node = (state) => {
  // 暂停并显示当前内容以供审查（出现在 result.__interrupt__ 中）
  const editedContent = interrupt({
    instruction: "Review and edit this content",
    content: state.generatedText
  });

  // 使用编辑后的内容更新状态
  return { generatedText: editedContent };
}

恢复时，提供编辑后的内容：

await graph.invoke(
  new Command({ resume: "The edited and improved text" }), // 该值成为 interrupt() 的返回值
  config
);

完整示例

import {
  Command,
  MemorySaver,
  START,
  END,
  StateGraph,
  StateSchema,
  interrupt,
} from "@langchain/langgraph";
import * as z from "zod";

const State = new StateSchema({
  generatedText: z.string(),
});

const builder = new StateGraph(State)
  .addNode("review", async (state) => {
    // 请求审查者编辑生成的内容
    const updated = interrupt({
      instruction: "Review and edit this content",
      content: state.generatedText,
    });
    return { generatedText: updated };
  })
  .addEdge(START, "review")
  .addEdge("review", END);

const checkpointer = new MemorySaver();
const graph = builder.compile({ checkpointer });

const config = { configurable: { thread_id: "review-42" } };
const initial = await graph.invoke({ generatedText: "Initial draft" }, config);
console.log(initial.__interrupt__);
// [{ value: { instruction: ..., content: ... } }]

// 使用审查者的编辑文本恢复
const finalState = await graph.invoke(
  new Command({ resume: "Improved draft after review" }),
  config,
);
console.log(finalState.generatedText); // -> "Improved draft after review"

工具中的中断

您还可以将中断直接放置在工具函数内部。这使得工具本身在被调用时会暂停等待批准，并允许在执行前对工具调用进行人工审查和编辑。首先，定义一个使用 interrupt 的工具：

import { tool } from "@langchain/core/tools";
import { interrupt } from "@langchain/langgraph";
import * as z from "zod";

const sendEmailTool = tool(
  async ({ to, subject, body }) => {
    // 在发送前暂停；载荷出现在 result.__interrupt__ 中
    const response = interrupt({
      action: "send_email",
      to,
      subject,
      body,
      message: "Approve sending this email?",
    });

    if (response?.action === "approve") {
      // 恢复值可以在执行前覆盖输入
      const finalTo = response.to ?? to;
      const finalSubject = response.subject ?? subject;
      const finalBody = response.body ?? body;
      return `Email sent to ${finalTo} with subject '${finalSubject}'`;
    }
    return "Email cancelled by user";
  },
  {
    name: "send_email",
    description: "Send an email to a recipient",
    schema: z.object({
      to: z.string(),
      subject: z.string(),
      body: z.string(),
    }),
  },
);

当您希望审批逻辑与工具本身一起存在，使其在图的不同部分可重用时，这种方法很有用。LLM 可以自然地调用该工具，中断会在工具被调用时暂停执行，允许您批准、编辑或取消该操作。

完整示例

import { tool } from "@langchain/core/tools";
import { ChatAnthropic } from "@langchain/anthropic";
import {
  Command,
  MemorySaver,
  START,
  END,
  StateGraph,
  StateSchema,
  MessagesValue,
  GraphNode,
  interrupt,
} from "@langchain/langgraph";
import * as z from "zod";

const sendEmailTool = tool(
  async ({ to, subject, body }) => {
    // 在发送前暂停；载荷出现在 result.__interrupt__ 中
    const response = interrupt({
      action: "send_email",
      to,
      subject,
      body,
      message: "Approve sending this email?",
    });

    if (response?.action === "approve") {
      const finalTo = response.to ?? to;
      const finalSubject = response.subject ?? subject;
      const finalBody = response.body ?? body;
      console.log("[sendEmailTool]", finalTo, finalSubject, finalBody);
      return `Email sent to ${finalTo}`;
    }
    return "Email cancelled by user";
  },
  {
    name: "send_email",
    description: "Send an email to a recipient",
    schema: z.object({
      to: z.string(),
      subject: z.string(),
      body: z.string(),
    }),
  },
);

const model = new ChatAnthropic({ model: "claude-sonnet-4-6" }).bindTools([sendEmailTool]);

const State = new StateSchema({
  messages: MessagesValue,
});

const agent: typeof State.Node = async (state) => {
  // LLM 可能决定调用工具；中断在发送前暂停
  const response = await model.invoke(state.messages);
  return { messages: [response] };
};

const graphBuilder = new StateGraph(State)
  .addNode("agent", agent)
  .addEdge(START, "agent")
  .addEdge("agent", END);

const checkpointer = new MemorySaver();
const graph = graphBuilder.compile({ checkpointer });

const config = { configurable: { thread_id: "email-workflow" } };
const initial = await graph.invoke(
  {
    messages: [
      { role: "user", content: "Send an email to alice@example.com about the meeting" },
    ],
  },
  config,
);
console.log(initial.__interrupt__); // -> [{ value: { action: 'send_email', ... } }]

// 使用批准和可选的编辑参数进行恢复
const resumed = await graph.invoke(
  new Command({
    resume: { action: "approve", subject: "Updated subject" },
  }),
  config,
);
console.log(resumed.messages.at(-1)); // -> send_email 返回的工具结果

验证人类输入

有时您需要验证来自人类的输入，如果值无效则重新提示。推荐的方法是在每次节点调用时只调用一次 interrupt()，将错误消息存储在状态中从节点返回，并使用条件边循环回该节点，直到提供有效值。

避免在单个节点内使用 while True + interrupt() 循环。 因为节点在每次恢复时都会从头开始重新运行（参见中断规则），调用 interrupt() 多次的循环会导致每次恢复时重播所有之前的迭代：第一次恢复重播 1 次迭代，第二次重播 2 次，依此类推。结果是循环体内的任何代码都会被指数级地重新执行。

正确的模式：

将重新提示的问题存储在状态中（例如 pendingQuestion）。
在节点中，只调用一次 interrupt()，传递状态中的当前问题。
如果答案无效，返回更新的 pendingQuestion，以便下次调用时重新提示。
使用 addConditionalEdges 路由回该节点，直到收集到有效值。

import { interrupt } from "@langchain/langgraph";

const getAgeNode: typeof State.Node = (state) => {
  const question = state.pendingQuestion ?? "你的年龄是多少?";
  const answer = interrupt(question); // 每次调用时只调用一次

  if (typeof answer === "number" && answer > 0) {
    return { age: answer, pendingQuestion: null };
  }
  return {
    pendingQuestion: `'${answer}' 不是有效的年龄。请输入一个正数。`,
  };
};

// builder.addConditionalEdges("collectAge", (state) =>
//   state.age !== null ? END : "collectAge"
// );

每次恢复恰好调用一次 getAgeNode，运行一次 interrupt() 调用，然后退出。当答案无效时，条件边循环回来，下一个中断使用更新的问题重新提示。

完整示例

import {
  Command,
  MemorySaver,
  START,
  END,
  StateGraph,
  StateSchema,
  interrupt,
} from "@langchain/langgraph";
import * as z from "zod";

const State = new StateSchema({
  age: z.number().nullable(),
  pendingQuestion: z.string().nullable(),
});

const builder = new StateGraph(State)
  .addNode("collectAge", (state) => {
    const question = state.pendingQuestion ?? "What is your age?";
    const answer = interrupt(question); // 每次调用只调用一次

    if (typeof answer === "number" && answer > 0) {
      return { age: answer, pendingQuestion: null };
    }
    return { pendingQuestion: `'${answer}' is not a valid age. Please enter a positive number.` };
  })
  .addEdge(START, "collectAge")
  .addConditionalEdges("collectAge", (state) =>
    state.age !== null ? END : "collectAge"
  );

const checkpointer = new MemorySaver();
const graph = builder.compile({ checkpointer });

const config = { configurable: { thread_id: "form-1" } };
const first = await graph.invoke({ age: null, pendingQuestion: null }, config);
console.log(first.__interrupt__); // -> [{ value: "What is your age?", ... }]

// 提供无效数据；节点通过条件边重新提示
const retry = await graph.invoke(new Command({ resume: "thirty" }), config);
console.log(retry.__interrupt__); // -> [{ value: "'thirty' is not a valid age...", ... }]

// 提供有效数据；路由返回 END，图完成
const final = await graph.invoke(new Command({ resume: 30 }), config);
console.log(final.age); // -> 30

中断规则

当您在节点内调用 interrupt 时，LangGraph 通过抛出一个特殊异常来挂起执行，该异常通知运行时暂停。此异常沿调用栈向上传播，并被运行时捕获，运行时随后通知图保存当前状态并等待外部输入。当执行恢复时（在您提供请求的输入后），运行时会从头开始重新启动整个节点——它不会从调用 interrupt 的确切代码行恢复。这意味着 interrupt 之前运行的任何代码都会再次执行。因此，在处理中断时需要遵循一些重要规则，以确保它们按预期行为。

不要用 try/catch 包裹 `interrupt` 调用

interrupt 在调用点暂停执行的方式是抛出一个特殊异常。如果您将 interrupt 调用包裹在 try/catch 块中，您将捕获此异常，中断将不会被传回图。

✅ 将 interrupt 调用与容易出错的代码分开
✅ 如有条件需要，有选择地捕获错误

const nodeA: GraphNode<typeof State> = async (state) => {
  // ✅ 好的做法：先中断，然后单独处理错误条件
  const name = interrupt("What's your name?");
  try {
    await fetchData(); // 此操作可能失败
  } catch (err) {
    console.error(error);
  }
  return state;
}

const nodeA: GraphNode<typeof State> = async (state) => {
  // ✅ 好的做法：重新抛出异常将允许中断被传回图
  try {
    const name = interrupt("What's your name?");
    await fetchData(); // 此操作可能失败
  } catch (err) {
    if (error instanceof NetworkError) {
      console.error(error);
    }
    throw error;
  }
  return state;
}

🔴 不要用裸的 try/catch 块包裹 interrupt 调用

async function nodeA(state: State) {
    // ❌ 坏的做法：用裸的 try/catch 包裹中断会捕获中断异常
    try {
        const name = interrupt("What's your name?");
    } catch (err) {
        console.error(error);
    }
    return state;
}

不要重新排序节点内的 `interrupt` 调用

在单个节点中使用多个中断很常见，然而如果不小心处理，这可能会导致意外行为。当一个节点包含多个中断调用时，LangGraph 会为执行该节点的任务维护一个恢复值列表。每当执行恢复时，它会从节点的开头开始。对于遇到的每个中断，LangGraph 会检查任务的恢复列表中是否存在匹配的值。匹配是严格基于索引的，因此节点内中断调用的顺序很重要。

✅ 在跨节点执行时保持 interrupt 调用一致

async function nodeA(state: State) {
    // ✅ 好的做法：中断调用每次都以相同的顺序发生
    const name = interrupt("What's your name?");
    const age = interrupt("What's your age?");
    const city = interrupt("What's your city?");

    return {
        name,
        age,
        city
    };
}

🔴 不要条件性地跳过节点内的 interrupt 调用
🔴 不要使用跨执行不确定性的逻辑（包括 while True 验证循环）来循环 interrupt 调用。请改用条件边（参见验证人类输入）

const nodeA: GraphNode<typeof State> = async (state) => {
  // ❌ 坏的做法：条件性地跳过中断会改变顺序
  const name = interrupt("What's your name?");

  // 在第一次运行时，这可能会跳过中断
  // 在恢复时，它可能不会跳过 - 导致索引不匹配
  if (state.needsAge) {
    const age = interrupt("What's your age?");
  }

  const city = interrupt("What's your city?");

  return { name, city };
}

const nodeA: GraphNode<typeof State> = async (state) => {
  // ❌ 坏的做法：基于非确定性数据进行循环
  // 中断的次数在执行之间会发生变化
  const results = [];
  for (const item of state.dynamicList || []) {  // 列表可能在运行之间发生变化
    const result = interrupt(`Approve ${item}?`);
    results.push(result);
  }

  return { results };
}

不要在 `interrupt` 调用中返回复杂值

根据使用的检查点器，复杂值可能无法序列化（例如，您无法序列化一个函数）。为了使您的图能够适应任何部署环境，最佳实践是只使用可以合理序列化的值。

✅ 将简单的、JSON 可序列化的类型传递给 interrupt
✅ 传递具有简单值的字典/对象

const nodeA: GraphNode<typeof State> = async (state) => {
  // ✅ 好的做法：传递可序列化的简单类型
  const name = interrupt("What's your name?");
  const count = interrupt(42);
  const approved = interrupt(true);

  return { name, count, approved };
}

const nodeA: GraphNode<typeof State> = async (state) => {
  // ✅ 好的做法：传递具有简单值的对象
  const response = interrupt({
    question: "Enter user details",
    fields: ["name", "email", "age"],
    currentValues: state.user || {}
  });

  return { user: response };
}

🔴 不要将函数、类实例或其他复杂对象传递给 interrupt

function validateInput(value: string): boolean {
    return value.length > 0;
}

const nodeA: GraphNode<typeof State> = async (state) => {
  // ❌ 坏的做法：将函数传递给中断
  // 该函数无法被序列化
  const response = interrupt({
    question: "What's your name?",
    validator: validateInput  // 这将失败
  });
  return { name: response };
}

class DataProcessor {
    constructor(private config: any) {}
}

const nodeA: GraphNode<typeof State> = async (state) => {
  const processor = new DataProcessor({ mode: "strict" });

  // ❌ 坏的做法：将类实例传递给中断
  // 该实例无法被序列化
  const response = interrupt({
    question: "Enter data to process",
    processor: processor  // 这将失败
  });
  return { result: response };
}

在 `interrupt` 之前调用的副作用必须是幂等的

因为中断的工作原理是重新运行它们被调用的节点，所以在 interrupt 之前调用的副作用（理想情况下）应该是幂等的。作为背景，幂等性意味着相同的操作可以多次应用，而不会在初始执行之外改变结果。例如，您可能在节点内部有一个更新记录的 API 调用。如果在该调用之后调用了 interrupt，当节点恢复时，它将被重新运行多次，可能会覆盖初始更新或创建重复记录。

✅ 在 interrupt 之前使用幂等操作
✅ 将副作用放在 interrupt 调用之后
✅ 尽可能将副作用分离到单独的节点中

const nodeA: GraphNode<typeof State> = async (state) => {
  // ✅ 好的做法：使用幂等的 upsert 操作
  // 多次运行将产生相同的结果
  await db.upsertUser({
    userId: state.userId,
    status: "pending_approval"
  });

const nodeA: GraphNode<typeof State> = async (state) => {
// ✅ 正确：将副作用置于中断之后
// 这确保了只有在收到批准后才会执行一次
const approved = interrupt("Approve this change?");

if (approved) {
  await db.createAuditLog({
    userId: state.userId,
    action: "approved"
  });
}

return { approved };
}

const approvalNode: GraphNode<typeof State> = async (state) => {
  // ✅ 正确：在此节点中仅处理中断
  const approved = interrupt("Approve this change?");

  return { approved };
}

const notificationNode: GraphNode<typeof State> = async (state) => {
  // ✅ 正确：副作用在独立的节点中发生
  // 这在批准后运行，因此只执行一次
  if (state.approved) {
    await sendNotification({
      userId: state.userId,
      status: "approved",
    });
  }

  return state;
}

🔴 不要在 interrupt 之前执行非幂等操作
🔴 在不检查记录是否存在的情况下，不要创建新记录

const nodeA: GraphNode<typeof State> = async (state) => {
  // ❌ 错误：在中断前创建新记录
  // 这会在每次恢复时创建重复记录
  const auditId = await db.createAuditLog({
    userId: state.userId,
    action: "pending_approval",
    timestamp: new Date()
  });

  const approved = interrupt("Approve this change?");

  return { approved, auditId };
}

const nodeA: GraphNode<typeof State> = async (state) => {
  // ❌ 错误：在中断前向数组追加内容
  // 这会在每次恢复时添加重复条目
  await db.appendToHistory(state.userId, "approval_requested");

  const approved = interrupt("Approve this change?");

  return { approved };
}

与作为函数调用的子图一起使用

当在节点内调用子图时，父图将从触发子图调用和 interrupt 的节点开头恢复执行。同样，子图也会从调用 interrupt 的节点开头恢复执行。

async function nodeInParentGraph(state: State) {
    someCode(); // <-- 恢复时，这将重新执行
    // 作为函数调用一个子图。
    // 该子图包含一个 `interrupt` 调用。
    const subgraphResult = await subgraph.invoke(someInput);
    // ...
}

async function nodeInSubgraph(state: State) {
    someOtherCode(); // <-- 恢复时，这也将重新执行
    const result = interrupt("What's your name?");
    // ...
}

使用中断进行调试

要调试和测试图，你可以使用静态中断作为断点，逐节点地单步执行图的执行过程。静态中断在节点执行之前或之后的定义点触发。你可以在编译图时通过指定 interruptBefore 和 interruptAfter 来进行设置。

静态中断不推荐用于人机交互工作流。请改用 interrupt 函数。

编译时
运行时

const graph = builder.compile({
    interruptBefore: ["node_a"],
    interruptAfter: ["node_b", "node_c"],
    checkpointer,
});

// 为图传递一个线程 ID
const config = {
    configurable: {
        thread_id: "some_thread"
    }
};

// 运行图直到断点处
await graph.invoke(inputs, config);# [!code highlight]

await graph.invoke(null, config);  # [!code highlight]

断点是在 compile（编译）时设置的。
interruptBefore 指定在节点执行前应暂停执行的节点。
interruptAfter 指定在节点执行后应暂停执行的节点。
需要一个检查点记录器（checkpointer）来启用断点。
图会运行直到命中第一个断点。
通过传入 null 作为输入来恢复图。这将运行图直到命中下一个断点。

// 运行图直到断点处
graph.invoke(inputs, {
    interruptBefore: ["node_a"],
    interruptAfter: ["node_b", "node_c"],
    configurable: {
        thread_id: "some_thread"
    }
});

// 恢复图的执行
await graph.invoke(null, config);

调用 graph.invoke 时带有 interruptBefore 和 interruptAfter 参数。这是一个运行时配置，可以每次调用时更改。
interruptBefore 指定在节点执行前应暂停执行的节点。
interruptAfter 指定在节点执行后应暂停执行的节点。
图会运行直到命中第一个断点。
通过传入 null 作为输入来恢复图。这将运行图直到命中下一个断点。

要调试你的中断，请使用 LangSmith。

使用 LangSmith Studio

你可以在运行图之前，通过 LangSmith Studio 的 UI 界面为你的图设置静态中断。你也可以使用 UI 在执行过程中的任意节点检查图的状态。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Capabilities

Production

Frontend

LangGraph APIs

中断

使用 `interrupt` 暂停

恢复中断

常见模式

使用人在回路 (HITL) 中断进行流式处理

处理多个中断

批准或拒绝

审查和编辑状态

工具中的中断

验证人类输入

中断规则

不要用 try/catch 包裹 `interrupt` 调用

不要重新排序节点内的 `interrupt` 调用

不要在 `interrupt` 调用中返回复杂值

在 `interrupt` 之前调用的副作用必须是幂等的

与作为函数调用的子图一起使用

使用中断进行调试

使用 LangSmith Studio

​使用 interrupt 暂停

​恢复中断

​常见模式

​使用人在回路 (HITL) 中断进行流式处理

​处理多个中断

​批准或拒绝

​审查和编辑状态

​工具中的中断

​验证人类输入

​中断规则

​不要用 try/catch 包裹 interrupt 调用

​不要重新排序节点内的 interrupt 调用

​不要在 interrupt 调用中返回复杂值

​在 interrupt 之前调用的副作用必须是幂等的

​与作为函数调用的子图一起使用

​使用中断进行调试

​使用 LangSmith Studio

使用 `interrupt` 暂停

恢复中断

常见模式

使用人在回路 (HITL) 中断进行流式处理

处理多个中断

批准或拒绝

审查和编辑状态

工具中的中断

验证人类输入

中断规则

不要用 try/catch 包裹 `interrupt` 调用

不要重新排序节点内的 `interrupt` 调用

不要在 `interrupt` 调用中返回复杂值

在 `interrupt` 之前调用的副作用必须是幂等的

与作为函数调用的子图一起使用

使用中断进行调试

使用 LangSmith Studio