跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.ag-kit.dev/llms.txt

Use this file to discover all available pages before exploring further.

人机交互循环（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发送的id、reason和payload
  • resume(payload)：发送用户响应数据以恢复执行流程