原创秋山墨客 2025-07-18 08:30 江苏

AG-UI与CopilotKit实战：生成式UI与HITL流程

?k=1579d91f&u=https%3A%2F%2Fmmbiz.qpic

点击上方

蓝字

关注我们

?k=c4576a99&u=https%3A%2F%2Fmmbiz.qpic

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

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

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

01

CopilotKit能力之：基于Agent的生成式UI

【什么是基于Agent的生成式UI】

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

?k=f92b87d6&u=https%3A%2F%2Fmmbiz.qpic

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

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

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

?k=ae4f2ffa&u=https%3A%2F%2Fmmbiz.qpic

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

?k=e7d85ae5&u=https%3A%2F%2Fmmbiz.qpic

【实例演示】

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

步骤一：增强Agent的State

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

class AgentState(CopilotKitState):
    # 搜索历史记录，格式: [{"tool_name":"xxx","query": "关键词", "completed": True/False, "timestamp": "时间戳"}]    
    search_history: list[dict] = []

步骤二：更新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（暂不考虑同时有多个搜索的情况）。

步骤三：将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界面即可。

前端效果测试

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

?k=202246ec&u=https%3A%2F%2Fmmbiz.qpic

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

02

CopilotKit能力之：HITL（人类参与流程）

【什么是HITL】

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

?k=7ccac154&u=https%3A%2F%2Fmmbiz.qpic

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

?k=55bd9c3e&u=https%3A%2F%2Fmmbiz.qpic

?k=6642eb2f&u=https%3A%2F%2Fmmbiz.qpic

关于LangGraph的HTIL机制的学习，可以回顾：

彻底说清 Human-in-the-Loop【上】：挑战与LangGraph解法【上】

彻底说清 Human-in-the-Loop【下】：分布式环境下的挑战与应对

?k=c04872b9&u=https%3A%2F%2Fmmbiz.qpic

【实例演示】

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

步骤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"]:
        ....
    # 如果审核通过，执行工具调用
    elif approve_status in ["approved", "approve"]:
        ....

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

步骤2：增加前端UI的中断处理

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

useLangGraphInterrupt({
      render: ({ event, resolve }) => {
          const { tool_name, tool_args } = event.value;
          return (
              <divclassName="bg-gradient-to-br from-blue-50 to-indigo-50 border border-blue-200 rounded-2xl p-6 my-4 shadow-lg">
                  {/* 显示终端输出的消息，如标题，工具信息 */}
                  <divclassName="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可以把反馈传递给后端

前端效果测试

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

?k=1fde2dc2&u=https%3A%2F%2Fmmbiz.qpic

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

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

03

其他与总结

通过以上实战，我们逐步构建了一个基于 CopilotKit 的前后端 AI 助手应用，并深入演示了 AG-UI 协议带来的强大功能：

基本的事件流对话
状态同步实现实时进度更新
前端工具丰富了 Agent 的操作能力
生成式 UI提升了信息呈现效果
通过HITL保障了关键决策的人为把控

可以看到，CopilotKit 所代表的 AG-UI 协议为构建下一代智能应用奠定了良好的基础——让 AI Agent 真正融入应用界面，与用户共同完成任务。

更多扩展：CopilotKit 作为 AG-UI 的参考实现，仍在快速演进中。它已经支持与多种 Agent 框架的集成，使开发者可以自由选择后端技术栈。CopilotKit 还提供了一些高级功能，例如多 Agent 协调（同时管理多个 Agent 对话流）、安全隔离（通过 Secure Proxy 控制敏感数据和指令）等，实际项目中，这些特性可以帮助你打造生产级的 AI 助手应用。

工程意义：总结来说，AG-UI 协议和 CopilotKit 框架极大降低了将 AI 能力融合到产品界面中的门槛。从前端工程师的角度，你无需深究复杂的后端 AI 推理流程，只需使用熟悉的 React 组件和 Hooks，即可调动强大的AI为你的应用服务。从后端AI工程师的角度，你也无需操心前端展示，只要按照协议产出标准事件，UI 就会自动配合渲染。这种清晰的前后端职责分离与协同，使AI应用开发更加高效与标准化。

相信随着社区的完善和更多公司的参与，AG-UI 有望成为智能体人机交互的事实标准 ——让每一个应用都能轻松接入 AI，每一位用户都能享受人机共助的高效体验。

本文Demo源码：

https://github.com/pingcy/copilot-ai-demo