跳到主要内容
支持地域：上海

LangGraph TS 适配器

让 LangGraph 工作流支持 AG-UI 协议。

什么是 AG-UI？​

AG-UI 是一个开放、轻量级、基于事件的协议，用于标准化 AI Agent 与用户界面的交互。它让 Agent 可以：

  • 实时流式对话
  • 双向状态同步
  • 前端工具集成（Client Tools）
  • 人机协作（Human-in-the-loop）

这个包解决什么问题？​

  • 让 LangGraph 工作流支持 AG-UI 协议：将编译后的 LangGraph StateGraph 适配为 AG-UI 兼容的 Agent
  • 客户端状态管理：提供 ClientStateAnnotation 和 ClientState，让工作流可以接收前端传递的工具和消息

核心概念​

导出说明
LanggraphAgent将编译后的 LangGraph 工作流包装为 AG-UI 兼容的 Agent
ClientStateAnnotation预定义的 LangGraph 状态注解，包含 messages（消息历史）和 client.tools（客户端工具）
ClientStateClientStateAnnotation 对应的 TypeScript 类型，用于节点函数的参数类型

配合使用​

包名作用
@cloudbase/agent-server将 Agent 部署为 AG-UI 兼容的 HTTP 服务
@langchain/langgraphLangGraph 工作流框架
@langchain/openaiOpenAI 兼容模型接入

架构图​

安装​

pnpm add @cloudbase/agent-adapter-langgraph @cloudbase/agent-server @langchain/langgraph @langchain/openai

快速开始​

1. 创建 LangGraph 工作流​

// agent.ts
import { ChatOpenAI } from "@langchain/openai";
import { SystemMessage } from "@langchain/core/messages";
import { RunnableConfig } from "@langchain/core/runnables";
import { Command, StateGraph, END, START, MemorySaver } from "@langchain/langgraph";
import {
  ClientStateAnnotation,
  LanggraphAgent,
  ClientState,
} from "@cloudbase/agent-adapter-langgraph";

// 定义聊天节点
async function chatNode(state: ClientState, config?: RunnableConfig) {
  const model = new ChatOpenAI({
    model: process.env.OPENAI_MODEL!,
    apiKey: process.env.OPENAI_API_KEY,
    configuration: {
      baseURL: process.env.OPENAI_BASE_URL,
    },
  });

  // 绑定客户端工具
  const modelWithTools = model.bindTools([...(state.client?.tools || [])], {
    parallel_tool_calls: false,
  });

  const systemMessage = new SystemMessage({
    content: "你是一位乐于助人的 AI 助手。",
  });

  const response = await modelWithTools.invoke(
    [systemMessage, ...state.messages],
    config
  );

  return new Command({
    goto: END,
    update: { messages: [response] },
  });
}

// 构建工作流
const workflow = new StateGraph(ClientStateAnnotation)
  .addNode("chat_node", chatNode)
  .addEdge(START, "chat_node")
  .addEdge("chat_node", END);

const compiledGraph = workflow.compile({
  checkpointer: new MemorySaver(),
});

// 导出 createAgent 函数
export function createAgent() {
  return {
    agent: new LanggraphAgent({ compiledWorkflow: compiledGraph }),
  };
}

2. 部署为 HTTP 服务​

// index.ts
import { createExpressRoutes } from "@cloudbase/agent-server";
import { createAgent } from "./agent.js";
import express from "express";

const app = express();

createExpressRoutes({
  createAgent,
  express: app,
});

app.listen(9000, () => console.log("Listening on 9000!"));

3. 配置环境变量​

创建 .env 文件：

OPENAI_API_KEY=your-deepseek-api-key
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_MODEL=deepseek-chat

4. 启动服务​

npx tsx src/index.ts

完整的项目配置（tsconfig.json、package.json 等）请参考 示例项目。

API 参考​

LanggraphAgent​

将编译后的 LangGraph 工作流包装为 AG-UI 兼容的 Agent。

import { LanggraphAgent } from "@cloudbase/agent-adapter-langgraph";

const agent = new LanggraphAgent({
  compiledWorkflow: compiledGraph,  // StateGraph.compile() 的返回值
});

构造参数：

参数类型说明
compiledWorkflowCompiledStateGraph编译后的 LangGraph 工作流

ClientStateAnnotation​

预定义的状态注解，包含客户端工具和消息历史。用于构建支持 AG-UI 协议的 LangGraph 工作流。

import { ClientStateAnnotation, ClientState } from "@cloudbase/agent-adapter-langgraph";

const workflow = new StateGraph(ClientStateAnnotation)
  .addNode("chat_node", async (state: ClientState) => {
    // state.messages - 消息历史
    // state.client.tools - 客户端传递的工具
  });

ClientState​

ClientStateAnnotation 对应的 TypeScript 类型。用于定义节点函数的参数类型，让你可以在节点中访问消息历史和客户端工具。

async function chatNode(state: ClientState, config?: RunnableConfig) {
  // 访问消息历史
  const messages = state.messages;

  // 访问客户端传递的工具
  const tools = state.client?.tools || [];

  // ...
}

字段说明：

字段类型说明
messagesBaseMessage[]消息历史（来自 LangGraph 的 MessagesAnnotation）
client.toolsTool[]前端客户端传递的工具列表

相关资源​