人类在环

并非所有代理操作都应在无人监督的情况下运行。当代理即将发送电子邮件、删除记录、执行金融交易或执行任何不可逆操作时，您需要人工先审核并批准该操作。人类在环（HITL）模式允许您的代理暂停执行，将待处理操作呈现给用户，并仅在获得明确批准后恢复执行。

中断如何工作

LangGraph 代理支持中断，这是代理将控制权交还给客户端的显式暂停点。当代理遇到中断时：

代理停止执行并发出中断载荷
useStream 钩子通过 stream.interrupt 呈现该中断
您的 UI 渲染一个带有批准/拒绝/编辑选项的审核卡片
用户做出决定
您的代码使用恢复命令调用 stream.submit()
代理从上次中断处继续执行

为 HITL 设置 useStream

定义一个与代理状态模式匹配的 TypeScript 接口，并将其作为类型参数传递给 useStream，以实现对状态值的类型安全访问。在下面的示例中，请将 typeof myAgent 替换为您的接口名称：

import type { BaseMessage } from "@langchain/core/messages";

interface AgentState {
  messages: BaseMessage[];
}

import { useStream } from "@langchain/react";

const AGENT_URL = "http://localhost:2024";

export function Chat() {
  const stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "human_in_the_loop",
  });

  const interrupt = stream.interrupt;

  return (
    <div>
      {stream.messages.map((msg) => (
        <Message key={msg.id} message={msg} />
      ))}
      {interrupt && (
        <ApprovalCard
          interrupt={interrupt}
          onRespond={(response) =>
            stream.submit(null, { command: { resume: response } })
          }
        />
      )}
    </div>
  );
}

<script setup lang="ts">
import { useStream } from "@langchain/vue";

const AGENT_URL = "http://localhost:2024";

const stream = useStream<typeof myAgent>({
  apiUrl: AGENT_URL,
  assistantId: "human_in_the_loop",
});

function handleRespond(response: HITLResponse) {
  stream.submit(null, { command: { resume: response } });
}
</script>

<template>
  <div>
    <Message
      v-for="msg in stream.messages.value"
      :key="msg.id"
      :message="msg"
    />
    <ApprovalCard
      v-if="stream.interrupt.value"
      :interrupt="stream.interrupt.value"
      @respond="handleRespond"
    />
  </div>
</template>

<script lang="ts">
  import { useStream } from "@langchain/svelte";

  const AGENT_URL = "http://localhost:2024";

  const { messages, interrupt, submit } = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "human_in_the_loop",
  });

  function handleRespond(response: HITLResponse) {
    submit(null, { command: { resume: response } });
  }
</script>

<div>
  {#each $messages as msg (msg.id)}
    <Message message={msg} />
  {/each}

  {#if $interrupt}
    <ApprovalCard interrupt={$interrupt} onRespond={handleRespond} />
  {/if}
</div>

import { Component } from "@angular/core";
import { useStream } from "@langchain/angular";
import type { HITLResponse } from "langchain";

const AGENT_URL = "http://localhost:2024";

@Component({
  selector: "app-chat",
  template: `
    @for (msg of stream.messages(); track msg.id) {
      <app-message [message]="msg" />
    }
    @if (stream.interrupt()) {
      <app-approval-card
        [interrupt]="stream.interrupt()"
        (respond)="handleRespond($event)"
      />
    }
  `,
})
export class ChatComponent {
  stream = useStream<typeof myAgent>({
    apiUrl: AGENT_URL,
    assistantId: "human_in_the_loop",
  });

  handleRespond(response: HITLResponse) {
    this.stream.submit(null, { command: { resume: response } });
  }
}

中断载荷

当代理暂停时，stream.interrupt 包含一个具有以下结构的 HITLRequest：

interface HITLRequest {
  actionRequests: ActionRequest[];
  reviewConfigs: ReviewConfig[];
}

interface ActionRequest {
  action: string;
  args: Record<string, unknown>;
  description?: string;
}

interface ReviewConfig {
  allowedDecisions: ("approve" | "reject" | "edit" | "respond")[];
}

属性	描述
`actionRequests`	代理想要执行的待处理操作数组
`actionRequests[].action`	操作名称（例如 `"send_email"`、`"delete_record"`）
`actionRequests[].args`	操作的结构化参数
`actionRequests[].description`	可选的人类可读描述，说明该操作的作用
`reviewConfigs`	每个操作的配置，控制允许哪些决定
`reviewConfigs[].allowedDecisions`	显示哪些按钮：`"approve"`、`"reject"`、`"edit"`、`"respond"`

决定类型

HITL 模式支持四种决定类型：

批准

用户确认操作应按原样继续执行：

const response: HITLResponse = {
  decision: "approve",
};

stream.submit(null, { command: { resume: response } });

拒绝

用户拒绝操作，并可选择提供原因：

const response: HITLResponse = {
  decision: "reject",
  reason: "The email tone is too aggressive. Please revise.",
};

stream.submit(null, { command: { resume: response } });

当操作被拒绝时，代理会收到拒绝原因，并可以决定如何继续。它可能会重新措辞、提出澄清问题，或完全放弃该操作。

编辑

用户在批准前修改操作的参数：

const response: HITLResponse = {
  decision: "edit",
  args: {
    ...originalArgs,
    subject: "Updated subject line",
    body: "Revised email body with softer language.",
  },
};

stream.submit(null, { command: { resume: response } });

用户为“询问用户”风格的工具提供直接回复。message 成为工具结果，工具本身不会被执行：

const response: HITLResponse = {
  decision: "respond",
  message: "Blue.",
};

stream.submit(null, { command: { resume: response } });

当工具旨在作为人工输入的占位符时，请使用 respond——例如，一个 ask_user 工具，提示代理从用户那里收集信息。

构建 ApprovalCard

这是一个处理所有四种决定类型的完整审批卡片组件：

function ApprovalCard({
  interrupt,
  onRespond,
}: {
  interrupt: { value: HITLRequest };
  onRespond: (response: HITLResponse) => void;
}) {
  const request = interrupt.value;
  const [editedArgs, setEditedArgs] = useState(
    request.actionRequests[0]?.args ?? {}
  );
  const [rejectReason, setRejectReason] = useState("");
  const [respondMessage, setRespondMessage] = useState("");
  const [mode, setMode] = useState<"review" | "edit" | "reject" | "respond">("review");

  const action = request.actionRequests[0];
  const config = request.reviewConfigs[0];

  if (!action || !config) return null;

  return (
    <div className="rounded-lg border-2 border-amber-300 bg-amber-50 p-4">
      <h3 className="font-semibold text-amber-800">需要操作审核</h3>
      <p className="mt-1 text-sm text-amber-700">
        {action.description ?? `代理想要执行：${action.action}`}
      </p>

      <div className="mt-3 rounded bg-white p-3 font-mono text-sm">
        <pre>{JSON.stringify(action.args, null, 2)}</pre>
      </div>

      {mode === "review" && (
        <div className="mt-4 flex gap-2">
          {config.allowedDecisions.includes("approve") && (
            <button
              className="rounded bg-green-600 px-4 py-2 text-white"
              onClick={() => onRespond({ decision: "approve" })}
            >
              批准
            </button>
          )}
          {config.allowedDecisions.includes("reject") && (
            <button
              className="rounded bg-red-600 px-4 py-2 text-white"
              onClick={() => setMode("reject")}
            >
              拒绝
            </button>
          )}
          {config.allowedDecisions.includes("edit") && (
            <button
              className="rounded bg-blue-600 px-4 py-2 text-white"
              onClick={() => setMode("edit")}
            >
              编辑
            </button>
          )}
          {config.allowedDecisions.includes("respond") && (
            <button
              className="rounded bg-purple-600 px-4 py-2 text-white"
              onClick={() => setMode("respond")}
            >
              回复
            </button>
          )}
        </div>
      )}

      {mode === "reject" && (
        <div className="mt-4 space-y-2">
          <textarea
            className="w-full rounded border p-2"
            placeholder="拒绝原因..."
            value={rejectReason}
            onChange={(e) => setRejectReason(e.target.value)}
          />
          <button
            className="rounded bg-red-600 px-4 py-2 text-white"
            onClick={() =>
              onRespond({ decision: "reject", reason: rejectReason })
            }
          >
            确认拒绝
          </button>
        </div>
      )}

      {mode === "edit" && (
        <div className="mt-4 space-y-2">
          <textarea
            className="w-full rounded border p-2 font-mono text-sm"
            value={JSON.stringify(editedArgs, null, 2)}
            onChange={(e) => {
              try {
                setEditedArgs(JSON.parse(e.target.value));
              } catch {
                // 允许编辑时输入无效的 JSON
              }
            }}
          />
          <button
            className="rounded bg-blue-600 px-4 py-2 text-white"
            onClick={() =>
              onRespond({ decision: "edit", args: editedArgs })
            }
          >
            提交编辑
          </button>
        </div>
      )}

      {mode === "respond" && (
        <div className="mt-4 space-y-2">
          <textarea
            className="w-full rounded border p-2"
            placeholder="您的回复..."
            value={respondMessage}
            onChange={(e) => setRespondMessage(e.target.value)}
          />
          <button
            className="rounded bg-purple-600 px-4 py-2 text-white"
            onClick={() =>
              onRespond({ decision: "respond", message: respondMessage })
            }
          >
            发送回复
          </button>
        </div>
      )}
    </div>
  );
}

恢复流程

用户做出决定后，完整流程如下：

调用 stream.submit(null, { command: { resume: hitlResponse } })
useStream 钩子将恢复命令发送到 LangGraph 后端
代理接收 HITLResponse 并继续执行。HITL 响应可能是以下之一：
- "approve"：代理继续执行下一个操作
- "reject"：代理接收拒绝理由并决定下一步
- "edit"：代理使用编辑后的参数运行工具
- "respond"：人工的消息直接作为工具结果返回，而不执行工具
随着代理恢复流式传输，interrupt 属性重置为 null

您可以在单次代理运行中链接多个 HITL 检查点。例如，代理可能会请求批准进行搜索，然后在发送包含结果的电子邮件之前再次请求批准。每个中断都独立处理。

常见用例

用例	操作	审核配置
发送电子邮件	`send_email`	`["approve", "reject", "edit"]`
数据库写入	`update_record`	`["approve", "reject"]`
金融交易	`transfer_funds`	`["approve", "reject"]`
文件删除	`delete_files`	`["approve", "reject"]`
调用外部服务的 API	`call_api`	`["approve", "reject", "edit"]`
收集用户输入	`ask_user`	`["respond"]`

处理多个待处理操作

当代理想要同时执行多个操作时，一个中断可以包含多个 actionRequests。为每个操作渲染一个卡片，并在恢复前收集所有决定：

function MultiActionReview({
  interrupt,
  onRespond,
}: {
  interrupt: { value: HITLRequest };
  onRespond: (responses: HITLResponse[]) => void;
}) {
  const [decisions, setDecisions] = useState<Record<number, HITLResponse>>({});
  const request = interrupt.value;

  const allDecided =
    Object.keys(decisions).length === request.actionRequests.length;

  return (
    <div className="space-y-4">
      {request.actionRequests.map((action, i) => (
        <SingleActionCard
          key={i}
          action={action}
          config={request.reviewConfigs[i]}
          onDecide={(response) =>
            setDecisions((prev) => ({ ...prev, [i]: response }))
          }
        />
      ))}
      {allDecided && (
        <button
          className="rounded bg-green-600 px-4 py-2 text-white"
          onClick={() =>
            onRespond(
              request.actionRequests.map((_, i) => decisions[i])
            )
          }
        >
          提交所有决定
        </button>
      )}
    </div>
  );
}

最佳实践

实施 HITL 工作流时，请牢记以下准则：

显示清晰的上下文。始终显示代理想要做什么以及为什么。包括操作描述和完整参数。
使批准成为最简单的路径。如果操作看起来正确，批准应该只需一次点击。将多步骤流程保留给拒绝/编辑。
验证编辑后的参数。当用户编辑操作参数时，在发送前验证 JSON 结构。对格式错误的输入显示内联错误。
持久化中断状态。如果用户刷新页面，中断仍应可见。useStream 通过线程的检查点处理此问题。
记录所有决定。对于审计跟踪，记录每个批准/拒绝/编辑决定，包括时间戳和做出决定的用户。
谨慎设置超时。长时间运行的代理不应在人工审核上无限期阻塞。考虑显示代理已等待了多长时间。

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交问题。

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Deploy with LangSmith

中断如何工作

为 HITL 设置 useStream

中断载荷

决定类型

批准

拒绝

编辑

回复

构建 ApprovalCard

恢复流程

常见用例

处理多个待处理操作

最佳实践

​中断如何工作

​为 HITL 设置 useStream

​中断载荷

​决定类型

​批准

​拒绝

​编辑

​回复

​构建 ApprovalCard

​恢复流程

​常见用例

​处理多个待处理操作

​最佳实践

中断如何工作

为 HITL 设置 useStream

中断载荷

决定类型

批准

拒绝

编辑

回复

构建 ApprovalCard

恢复流程

常见用例

处理多个待处理操作

最佳实践