CopilotKit 与 LangGraph 集成：构建 Agent 原生应用前端交互框架

• 双向状态同步：前端可读取 Agent 状态，也可主动修改状态并同步至后端
• 运行状态监控：通过 running 属性实时获取 Agent 执行状态
• 执行控制：提供 stop() 方法用于中断 Agent 执行

适用场景

useCoAgent 适用于需要在应用任意位置访问和修改 Agent 状态的场景，例如：

• 构建状态面板展示 Agent 当前工作进度
• 实现用户对 Agent 状态的手动干预
• 在多个组件间共享 Agent 上下文

2.2 useAgent：v2 版本的增强型 Hook

useAgent 是 CopilotKit v1.50 版本引入的新一代 Hook，作为 useCoAgent 的超集，提供了更完整的 Agent 控制能力。

核心特性

import { useAgent } from "@copilotkit/react-core/v2";

const { agent } = useAgent({ agentId: "my-agent" });
// 状态管理
agent.state;
agent.setState;
// 消息控制
agent.messages;
agent.setMessages;
// 执行控制
agent.sendMessage();
agent.runAgent();

新增能力

多 Agent 协调示例

const { agent: langgraph } = useAgent({ agentId: "langgraph" });
const { agent: pydantic } = useAgent({ agentId: "pydantic" });

// 并行执行多个 Agent
[langgraph, pydantic].forEach((agent) => {
  agent.addMessage({
    id: crypto.randomUUID(),
    role: "user",
    content: message,
  });
  agent.runAgent();
});

// Agent 间状态共享
langgraph.setMessages(pydantic.messages);

2.3 对比总结

选型建议：对于新项目，推荐使用 useAgent 以获得更完整的功能支持；对于已有项目，useCoAgent 仍可正常使用，两者可在同一应用中混合使用。

三、useRenderToolCall 与 useCoAgentStateRender 对比分析

这两个 Hook 均用于在聊天界面中渲染自定义 UI 组件，但其触发机制和应用场景存在本质区别。

3.1 useRenderToolCall：工具调用渲染

useRenderToolCall 是一个纯渲染 Hook，用于在 Agent 调用工具时展示自定义 UI，而不执行任何业务逻辑。

核心特性

useRenderToolCall({
  name: "internet_search",
  render: ({ args, status, result }) => (
    <div className="tool-card">
      <div className="tool-header"> 🔍 {status === "complete" ? "搜索完成" : "搜索中..."}</div>
      <div className="tool-query">查询:{args?.query}</div>
      {status === "executing" && <Spinner />}
    </div>
  ),
});

渲染参数

适用场景

• 展示搜索工具的查询进度和结果预览
• 渲染任务规划工具创建的待办列表
• 显示文件操作工具的执行状态
• 任何需要可视化工具调用过程的场景

3.2 useCoAgentStateRender：状态变更渲染

useCoAgentStateRender 用于基于 Agent 状态变更在聊天界面中渲染 UI 组件，其触发时机与工具调用无关，而是与 Agent 状态的更新周期绑定。

核心特性

useCoAgentStateRender<AgentState>({
  name: "research_agent",
  render: ({ state, status }) => {
    if (status === "inProgress" && !state?.findings?.length) {
      return (
        <div className="findings-card loading">
          <Spinner /> 正在研究中...
        </div>
      );
    }
    if (!state?.findings?.length) return null;
    return (
      <div className="findings-card">
        <h3>🔍 研究发现:{state.research_topic}</h3>
        <ul>{state.findings.map((finding, i) => (<li key={i}>{finding}</li>))}</ul>
        {state.summary && (<p className="summary">{state.summary}</p>)}
      </div>
    );
  },
});

渲染参数

状态发射机制

在后端 LangGraph Agent 中，需要使用 copilotkit_emit_state 函数手动发射状态更新：

from copilotkit.langchain import copilotkit_emit_state

async def research_node(state: AgentState) -> dict:
    # 执行研究逻辑
    findings = await perform_research(state["topic"])
    # 发射状态更新至前端
    await copilotkit_emit_state({"findings": findings, "research_topic": state["topic"]})
    return {"findings": findings}

适用场景

• 展示 Agent 的整体工作进度
• 渲染累积的研究发现或分析结果
• 实现人机协作（Human-in-the-Loop）工作流的状态展示
• 任何需要基于 Agent 状态变更触发 UI 更新的场景

3.3 对比总结

选型建议：

• 若需要展示单个工具的调用过程和结果，使用 useRenderToolCall
• 若需要基于 Agent 整体状态变更渲染 UI，使用 useCoAgentStateRender
• 两者可在同一应用中组合使用，实现完整的 Agent 交互体验

四、实践示例

以下代码展示了如何在一个研究助手应用中综合运用上述 Hook：

4.1 前端实现

"use client";
import { CopilotKit, useCoAgent, useCoAgentStateRender, useRenderToolCall } from "@copilotkit/react-core";
import { CopilotChat } from "@copilotkit/react-ui";

interface AgentState {
  messages: unknown[];
  todos?: Array<{ task: string; done: boolean }>;
  research_findings?: string[];
}

// 工具调用渲染组件
function ToolCallRenderer() {
  useRenderToolCall({
    name: "write_todos",
    render: ({ args, status }) => {
      const tasks = args?.tasks as string[] | undefined;
      return (
        <div className="tool-card">
          <div className="tool-header"> 📋 {status === "complete" ? "计划已创建" : "正在创建计划..."}</div>
          {tasks && (
            <ul>{tasks.map((task, i) => <li key={i}>{task}</li>)}</ul>
          )}
        </div>
      );
    },
  });
  useRenderToolCall({
    name: "internet_search",
    render: ({ args, status }) => (
      <div className="tool-card">
        <div className="tool-header"> 🔍 {status === "complete" ? "搜索完成" : "搜索中..."}</div>
        <div>查询:{args?.query}</div>
      </div>
    ),
  });
  return null;
}

// 状态面板组件
function AgentStatusPanel({ agentName }: { agentName: string }) {
  const { state, running, stop } = useCoAgent<AgentState>({ name: agentName });
  return (
    <div className="status-panel">
      <div className="status-header">
        <span className={`status-dot ${running ? "running" : "idle"}`} />
        <span>状态:{running ? "运行中..." : "空闲"}</span>
        {running && <button onClick={() => stop()}>⏹ 停止</button>}
      </div>
      {state?.todos && state.todos.length > 0 && (
        <div className="todos-preview">
          <div>📋 任务计划:</div>
          {state.todos.map((todo, i) => (
            <div key={i} className={todo.done ? "done" : ""}>
              {todo.done ? "✅" : "⏳"}{todo.task}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

// 主应用组件
export default function App() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" agent="deep_agent">
      <AgentStatusPanel agentName="deep_agent" />
      <ToolCallRenderer />
      <CopilotChat labels={{ title: "研究助手", initial: "您好！请告诉我您想研究的主题。", }} />
    </CopilotKit>
  );
}

4.2 后端实现（LangGraph）

from typing import Annotated, List
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    todos: List[dict]
    research_findings: List[str]

@tool
def write_todos(tasks: List[str]) -> str:
    """创建任务计划"""
    return f"已创建 {len(tasks)} 个任务"

@tool
def internet_search(query: str) -> str:
    """搜索互联网"""
    # 实际实现中调用搜索 API
    return f"关于 '{query}' 的搜索结果..."

llm = ChatOpenAI(model="gpt-4")
tools = [write_todos, internet_search]
llm_with_tools = llm.bind_tools(tools)

async def agent_node(state: AgentState) -> dict:
    response = await llm_with_tools.ainvoke(state["messages"])
    return {"messages": [response]}

def build_graph():
    graph = StateGraph(AgentState)
    graph.add_node("agent", agent_node)
    graph.add_node("tools", ToolNode(tools))
    graph.add_edge(START, "agent")
    graph.add_conditional_edges("agent", should_continue)
    graph.add_edge("tools", "agent")
    return graph.compile()

五、总结

CopilotKit 为 LangGraph Agent 提供了完整的前端集成解决方案，通过 AG-UI 协议实现了 Agent 与 UI 之间的标准化通信。本文重点分析的四个核心 Hook 各有其适用场景：

• useCoAgent：适用于需要双向状态共享的基础场景
• useAgent：适用于需要完整 Agent 控制能力的高级场景，包括多 Agent 协调和线程持久化
• useRenderToolCall：适用于工具调用过程的可视化渲染
• useCoAgentStateRender：适用于基于 Agent 状态变更的 UI 渲染

开发者应根据具体业务需求选择合适的 Hook 组合，以构建流畅、直观的 Agent 原生应用体验。

参考资料

• CopilotKit 官方文档 - LangGraph 集成
• CopilotKit v1.50 发布公告
• AG-UI 协议介绍
• useCoAgent Hook 参考
• useAgent Hook 参考
• useRenderToolCall Hook 参考
• useCoAgentStateRender Hook 参考