LangGraph 集成与状态增强：Agent 框架的深度对接

LangGraph 集成与状态增强：Agent 框架的深度对接

学习目标

理解 CopilotKit 与 LangGraph 的深度集成：

• LangGraphAgent 的继承链与事件映射
• State Enrichment 将 CopilotKit 的 actions 和 context 注入 LangGraph 状态
• CustomEvent 的双向转换
• @ag-ui/langgraph 包的独立定位

前置知识

本章涉及事件驱动架构和 Agent 核心循环的通用原理，建议先阅读：

• 事件驱动 Agent 架构

项目实践

继承链

CopilotKitLangGraphAgent
  → AGUILangGraphAgent（@ag-ui/langgraph 包）
    → AbstractAgent（@ag-ui/client 包）

CopilotKit 的 LangGraphAgent 继承自 @ag-ui/langgraph 的 LangGraphAgent，仅添加 CopilotKit 特定的 CustomEvent 映射逻辑。

State Enrichment

CopilotKit 将自身的 actions 和 context 注入到 LangGraph 的图状态中：

State Enrichment 结构（源码验证）：
{
  copilotkit: {
    actions: StateEnrichment["ag-ui"]["tools"],    // 前端工具列表
    context: StateEnrichment["ag-ui"]["context"]   // 应用上下文
  }
}

注入方式：在 RunAgentInput 中通过 agentStates 字段传递给 LangGraph。

意义：

• LangGraph Agent 可以在图执行中访问 CopilotKit 的工具和上下文
• 工具定义被转换为 LangGraph 可理解的格式
• 上下文数据作为图的初始状态的一部分

CustomEvent 双向映射

LangGraph 的 emitCustomEvent 与 CopilotKit AG-UI 事件之间的转换：

LangGraph → AG-UI（源码验证）：

LangGraph CustomEvent	AG-UI 事件
CopilotKitManuallyEmitMessage	TEXT_MESSAGE_START + TEXT_MESSAGE_CONTENT + TEXT_MESSAGE_END
CopilotKitManuallyEmitToolCall	TOOL_CALL_START + TOOL_CALL_ARGS + TOOL_CALL_END

dispatchEvent 转换逻辑（伪代码）：
if (event.name === "CopilotKitManuallyEmitMessage") {
  subscriber.next({ type: TEXT_MESSAGE_START, messageId: event.value.message_id, ... });
  subscriber.next({ type: TEXT_MESSAGE_CONTENT, delta: event.value.message, ... });
  subscriber.next({ type: TEXT_MESSAGE_END, messageId: event.value.message_id });
}

LangGraph HTTP Agent

LangGraphHttpAgent 支持通过 HTTP 连接到远程 LangGraph 部署：

配置（伪代码）：
new LangGraphHttpAgent({
  url: "https://langgraph-deployment.com",
  assistantId: "my-assistant",
  headers: { Authorization: "Bearer ..." }
})

@ag-ui/langgraph 包

独立的 AG-UI LangGraph 集成层，不在 @copilotkit/ scope 下：

• LangGraphAgent：实现 AbstractAgent 接口的 LangGraph Agent
• LangGraphHttpAgent：HTTP 连接到 LangGraph Cloud
• State Enrichment 定义
• ProcessedEvents 类型

版本：@ag-ui/langgraph@0.0.34

问题与规避

问题	规避策略
LangGraph 的事件格式与 AG-UI 不完全匹配	dispatchEvent 做精确转换；新增事件类型需要同步更新映射
State Enrichment 数据过大	只注入必要的 actions 和 context；裁剪上下文数据
LangGraph 图状态与 Agent 状态不同步	每次 run 前通过 agentStates 注入最新状态

设计取舍

继承 vs 组合

继承（CopilotKit 的选择）：

• 优势：可以直接扩展 AGUILangGraphAgent 的行为
• 代价：紧耦合到父类实现

组合：

• 优势：更松耦合
• 代价：需要手动转发所有方法调用

CopilotKit 选择继承是因为只需要覆盖 dispatchEvent 这一个方法。

参考来源

• packages/runtime/src/lib/runtime/agent-integrations/langgraph/agent.ts
• packages/runtime/src/langgraph.ts
• @ag-ui/langgraph 包源码