一步步实战 CopilotKit（AG-UI协议）：生成式 UI 与集成 Human-in-the-Loop

1. 一步步实战 CopilotKit（AG-UI 协议）：生成式 UI 与集成 Human-in-the-Loop【下】

在上篇（一步步实战 CopilotKit（AG-UI 协议）：快速集成前端 UI 与后端 Agent 的神器【上】）中，我们借助 CopilotKit 在前端 UI 中快速集成了一个 AI 助手并连接到后端 LangGraph Agent，初步展示了 AG-UI 协议的应用场景与 CopilotKit 的能力，比如前后端的状态共享、Agent 调用 UI"工具"等。

本篇将延续这个 Demo，继续探索其他重要场景的应用：

基于 Agent 的生成式 UI
HITL（人类参与流程）
其他与总结

1.1. 基于 Agent 的生成式 UI

1.1.1. 什么是基于 Agent 的生成式 UI

所谓"生成式 UI"，是指 UI 界面元素是由后端 Agent 的输出动态生成或配置的 UI 组件。即：Agent 可以在运行过程中通知前端应用，并发送必要的状态信息或数据，由前端生成某种定制的 UI 元素并渲染。

微信文章图片

比如用户询问 AI 助手："请展示我最近的所有交易记录。"Agent 可能会以文本形式罗列交易记录返回，既不直观也缺乏交互性。而利用生成式 UI，我们可以方便的呈现表格、图表等富界面来展示结果，让用户查看和操作更方便。

实际 Agent 应用中，生成式 UI 常用在两种场景：

前端将后端 Agent 运行中的状态变化（比如步骤）实时渲染到对话界面。比如：

前端将后端 Agent 的某个工具调用结果实时渲染到 Copilot 的对话界面。比如：

微信文章图片

1.1.2. 实例演示

我们对之前的 Demo 继续增强，演示如何把后端 Agent 的执行状态实时渲染到前端 Copilot 的 Chat 界面上。

1.1.2.1. 步骤一：增强 Agent 的 State

为了让前端能够知道 Agent 执行状态（这里主要是搜索工具的调用状态），首先在 Agent 的 State 中对原来保存的搜索信息做增强，使其能够体现出是否已经完成：

class AgentState(CopilotKitState):

1.1.2.2. 步骤二：更新 Agent 的执行状态

接下来要让 Agent 实时更新这个 State，在这个例子中，即能够在搜索前生成搜索记录，并在搜索后设置该记录的 completed 为 True。这需要修改工具调用节点的代码：

search_history = state.get("search_history", [])
# 找到最近的未完成搜索记录并标记为完成
for record in reversed(search_history):
    if record.get("tool_name") == tool_name:
        record["completed"] = True
        break
updated_state["search_history"] = search_history

这里找到最近开始的搜索记录，将其 completed 设置为 True（暂不考虑同时有多个搜索的情况）。

1.1.2.3. 步骤三：将 Agent 状态渲染到前端

在前端 page.tsx 页面上将 Agent 的执行状态实时渲染到 Chat 界面，只需要使用 useCoAgentStateRender 这个 Hook 函数即可：

function Home() {
  useCoAgentStateRender<AgentState>({
    name: "sample_agent",
    render: ({ state }) => (
      <div>
        {state.search_history?.map((search, index) => (
          <div key={index}>
            {search.completed ? "✅" : "❌"} 正在执行：{search.query} {search.completed ? "" : "……"}
          </div>
        ))}
      </div>
    ),
  });
}

给这个 Hook 提供一个 render 函数：将实时同步过来的 Agent 状态渲染到 Copilot 的 Chat 界面即可。

1.1.2.4. 前端效果测试

在前端 Copilot 发起一个需要搜索的任务，可以观察到界面上会实时展示 Agent 执行的搜索动作与状态。这里注意区分在上篇介绍的状态同步渲染到主界面，而这里是渲染到 Copilot 的 Chat 界面：

微信文章图片

除了把 Agent 的状态实时渲染，你还可以把 Agent 任务过程中某个工具的执行结果直接渲染到 UI，具体请参考我们的源代码。

1.2. HITL（人类参与流程）

1.2.1. 什么是 HITL

**HITL（Human-In-The-Loop，人类参与流程）**指的是在 AI Agent 执行过程中，引入人工的决策或反馈环节，以保证重要步骤的正确性或安全性。在许多实际场景中，我们并不希望 Agent 完全自主完成所有操作，而是在关键节点暂停，征求一下用户的意见或确认，再继续执行：

微信文章图片

CopilotKit 对 HITL 提供了很好的支持，开发者可以非常方便地定义这些交互式中断点。而在我们的 LangGraph 的 Demo 中，由于 LangGraph 框架本身就具有较为完善的 HITL 中断处理流程的支持，因此与 CopilotKit 的协作也更加便捷。

1.2.2. 实例演示

继续将之前的 Demo 中增加人类参与的环节：针对工具的使用加入人工审核环节（实际应用中你可以根据需要在不同的环节设置审核流程）。

1.2.2.1. 步骤四：给 Agent 增加中断环节

由于需要对工具的使用做审核，所以我们在调用工具的节点（tool_node）中加入一个中断环节，以等待人工审核的结果即可，核心逻辑如下：

approval_request = {
    "type": "tool_approval_request",
    "tool_name": tool_call.get("name"),
    "tool_args": tool_call.get("args", {}),
    "tool_id": tool_call.get("id"),
    "timestamp": "2025-07-08"
}

# 使用简化的审核流程 - 直接通过
approve_status = interrupt(approval_request)
if approve_status in ["rejected", "reject"]:
    # 处理拒绝逻辑
    pass
# 如果审核通过，执行工具调用
elif approve_status in ["approved", "approve"]:
    # 处理通过逻辑
    pass

这里调用 LangGraph 提供的 interrupt 产生中断，并等待用户反馈。approval_request 为中断时输出的结构化信息，通常用来展示给审核者查看。这里把调用的工具名称、参数等反馈到前端。

1.2.2.2. 步骤五：增加前端 UI 的中断处理

针对 LangGraph 的中断 CopilotKit 提供了 useLangGraphInterrupt Hook 函数，你可以透明的捕获 Agent 的中断请求，并在 Chat 界面上进行 UI 渲染和给予反馈：

useLangGraphInterrupt({
  render: ({ event, resolve }) => {
    const { tool_name, tool_args } = event.value;
    return (
      <div className="bg-gradient-to-br from-blue-50 to-indigo-50 border border-blue-200 rounded-2xl p-6 my-4 shadow-lg">
        {/* 显示终端输出的消息，如标题，工具信息 */}
        <div className="flex items-center gap-3 mb-4">
          {/* 工具信息展示 */}
        </div>
        {/* 这里用操作按钮用来给出反馈 */}
        <div className="mt-4">
          <div className="flex gap-2">
            <button type="button" onClick={() => resolve("approve")}>
              通过
            </button>
            <button type="button" onClick={() => resolve("reject")}>
              拒绝
            </button>
          </div>
        </div>
      </div>
    );
  }
});

这里的代码中，render 函数是处理中断的核心：

event：传递了从后端传来的中断事件，其中 event.value 包含了具体的中断数据，这里包括 tool_name、tool_args 等
resolve：则是用于解决中断的函数，通过 resolve 可以把反馈传递给后端

1.2.2.3. 前端效果测试

现在我们在前端的 Copilot 上发起一个请求，如果这个请求需要调用工具，你将会看到一个请求审核的 UI：

微信文章图片

点击通过后，Agent 将会继续执行；如果拒绝，Agent 将会结束流程。通过这样的机制，在 Agent 连贯执行的过程中插入了一个人工检查环节。CopilotKit 让这一切变得非常简单：前端只需定义好 UI 组件并调用 resolve 返回结果，底层通信和 Agent 等待/恢复的逻辑都由框架处理。对于用户来说，也能直观地在对话界面中完成交互，不需要跳出流程。

CopilotKit 的 HITL 支持不限于弹出对话框，也可以是更复杂的多步人工流程。通过引入 HITL，我们可以让 AI 系统在关键决策上保留人类掌控。例如自动化流程中，让用户确认支付是否执行；内容生成中，让用户挑选满意的版本；数据分析中，让用户选择关注的指标等等。这也是未来"人机共生"式智能应用的必备特性。