@cloudbase/agent-adapter-langgraph

@cloudbase/agent-adapter-langgraph

将 LangGraph 工作流转换为符合 AG-UI 协议 的 Agent。

安装

npm install @cloudbase/agent-adapter-langgraph

功能

• LanggraphAgent：将编译后的 LangGraph 工作流包装为 AG-UI 兼容的 Agent
• ClientStateAnnotation：工作流状态定义，包含 messages 和 client tools

快速开始

配合 @cloudbase/agent-server 使用

import { run } from "@cloudbase/agent-server";
import { StateGraph, START, END } from "@langchain/langgraph";
import { ClientStateAnnotation, LanggraphAgent } from "@cloudbase/agent-adapter-langgraph";

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

const compiledWorkflow = workflow.compile();

// 部署为 HTTP 服务
run({
  createAgent: () => ({
    agent: new LanggraphAgent({ compiledWorkflow }),
  }),
  port: 9000,
});

API 参考

LanggraphAgent

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

type LanggraphAgentConfig = AgentConfig & {
  compiledWorkflow: CompiledStateGraph; // 编译后的 LangGraph 工作流
  logger?: Logger;                      // 可选，日志实例
};

const agent = new LanggraphAgent(config);

• AgentConfig：来自 AG-UI 协议
• Logger：日志接口，详见 @cloudbase/agent-server 文档

ClientStateAnnotation

创建 LangGraph 工作流时使用的状态定义，已包含 AG-UI 需要的字段：

• messages：消息历史
• client.tools：客户端传来的工具列表

const workflow = new StateGraph(ClientStateAnnotation)
  .addNode("chat_node", chatNode)
  // ...

使用客户端工具

AG-UI 支持客户端工具（Client Tools）：客户端定义工具，Agent 调用后由客户端执行并返回结果。

适用场景：

• 需要访问客户端 API（如获取地理位置、访问剪贴板）
• 需要用户确认的操作（如发送邮件前确认）
• 需要展示 UI 交互（如让用户选择文件）

在 chatNode 中使用客户端工具

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

async function chatNode(state: ClientState) {
  const model = new ChatOpenAI({ model: "gpt-4o" });

  // 合并服务端工具和客户端工具
  const modelWithTools = model.bindTools([
    ...serverTools,              // 服务端定义的工具
    ...(state.client?.tools || []) // 客户端传来的工具
  ]);

  const response = await modelWithTools.invoke([...state.messages]);
  return { messages: [response] };
}

区分服务端工具和客户端工具

当 Agent 调用工具时，需要判断是服务端执行还是交给客户端：

const serverToolNames = new Set(serverTools.map(t => t.name));

function shouldContinue(state: ClientState): "tools" | "end" {
  const lastMessage = state.messages.at(-1) as AIMessage;

  if (lastMessage.tool_calls?.length) {
    // 如果是服务端工具，继续执行
    const hasServerTool = lastMessage.tool_calls.some(
      tc => serverToolNames.has(tc.name)
    );
    if (hasServerTool) return "tools";
  }

  // 客户端工具或无工具调用，结束并返回给客户端
  return "end";
}

依赖

• @langchain/langgraph：LangGraph 框架
• @langchain/core：LangChain 核心工具

文档

📚 完整文档请参阅 云开发 Agent 开发指南

相关资源

• AG-UI 协议
• LangGraph 文档