Skip to main content
人机交互循环(HITL)允许Agent在执行过程中暂停并请求用户输入或批准后再继续。这对于需要人工监督的场景至关重要,例如审批流程、表单提交或交互式决策。 其核心机制是中断功能:Agent在流式传输过程中发送中断事件,暂停执行直至客户端携带有效载荷恢复流程。

中断流程概览

以下是客户端与Agent在中断期间的交互高层级时序:

Agent端实现(简要概述)

在后端,Agent可触发中断:
  • AG-Kit:使用自定义控制流处理器返回{ action: 'interrupt', reason: '...', payload: { ... } }
  • LangGraph:使用图中的内置中断节点
具体实现请参阅各框架的专属文档。

客户端处理

重点介绍使用@ag-kit/ui-react包在React应用中的前端集成方案。

理解中断有效载荷

在深入代码前,先明确中断有效载荷的概念。 payload是Agent触发中断时发送的任意自定义数据,其内容完全由开发者根据Agent所需的用户输入类型决定。例如:
  • 审批流程中可能是待用户审核的步骤列表
  • 表单提交场景可以是定义表单字段的Schema
  • 支持任何JSON可序列化数据(如问题或选项)
Agent在后端决定有效载荷结构,前端据此渲染相应界面并返回用户响应数据。这种灵活性使得HITL能适应多样化场景。下文示例将展示基于步骤的审批流程有效载荷,但请注意:请根据实际用例自定义结构。

使用useChat钩子

useChat钩子通过interrupt选项支持HITL功能。以下是完整简单示例:
import { useChat } from "@ag-kit/ui-react";

function SimpleApprovalChat() {
  const { sendMessage, uiMessages, streaming } = useChat({
    url: "/your-agent-endpoint", // 替换为实际端点
    interrupt: {
      renderWithResume({ interrupt, resume }) {
        // 从有效载荷提取消息(假设结构为{ message: string })
        const message = (interrupt.payload as { message: string }).message;
        
        return (
          <div>
            <p>{message}</p>
            <button 
              onClick={() => resume({ approved: true })}
              disabled={streaming} 
            >
              批准
            </button>
            <button 
              onClick={() => resume({ approved: false })}
              disabled={streaming}
            >
              拒绝
            </button>
          </div>
        );
      },
    },
  });

  return (
    <div>
      {/* 简易消息展示 */}
      {uiMessages.map((msg, i) => (
        <div key={i} style={{ margin: "10px 0" }}>
          <strong>{msg.role}:</strong>
          {msg.parts.map((part, j) => (
            <div key={j}>
              {part.type === "text" && <p>{part.text}</p>}
              {part.type === "interrupt" && part.render?.()}
            </div>
          ))}
        </div>
      ))}
      <button 
        onClick={() => sendMessage("执行需要审批的操作")}
        disabled={streaming}
      >
        发送消息
      </button>
    </div>
  );
}
中断内容会以"interrupt"类型特殊部分的形式出现在uiMessages中:
  • interrupt:包含Agent发送的idreasonpayload
  • resume(payload):发送用户响应数据以恢复执行流程