LangGraph TS Adapter

Enable LangGraph workflows to support the AG-UI Protocol.

What is AG-UI?

AG-UI is an open, lightweight, event-based protocol for standardizing interactions between AI Agents and user interfaces. It enables Agents to:

• Real-time streaming conversations
• Bidirectional state synchronization
• Frontend tool integration (Client Tools)
• Human-in-the-loop collaboration

What does this package solve?

• Enable LangGraph workflows to support AG-UI protocol: Adapts compiled LangGraph StateGraph to be AG-UI compatible Agents
• Client state management: Provides ClientStateAnnotation and ClientState, allowing workflows to receive tools and messages from the frontend

Core Concepts

Export	Description
LanggraphAgent	Wraps compiled LangGraph workflow as an AG-UI compatible Agent
ClientStateAnnotation	Predefined LangGraph state annotation containing messages (message history) and client.tools (client tools)
ClientState	TypeScript type corresponding to ClientStateAnnotation, used for node function parameter types

Used Together With

Package	Purpose
@cloudbase/agent-server	Deploy Agent as an AG-UI compatible HTTP service
@langchain/langgraph	LangGraph workflow framework
@langchain/openai	OpenAI compatible model integration

Architecture Diagram

Installation

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

Quick Start

1. Create LangGraph Workflow

// 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";

// Define chat node
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,
    },
  });

  // Bind client tools
  const modelWithTools = model.bindTools([...(state.client?.tools || [])], {
    parallel_tool_calls: false,
  });

  const systemMessage = new SystemMessage({
    content: "You are a helpful AI assistant.",
  });

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

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

// Build workflow
const workflow = new StateGraph(ClientStateAnnotation)
  .addNode("chat_node", chatNode)
  .addEdge(START, "chat_node")
  .addEdge("chat_node", END);

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

// Export createAgent function
export function createAgent() {
  return {
    agent: new LanggraphAgent({ compiledWorkflow: compiledGraph }),
  };
}

2. Deploy as HTTP Service

// 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. Configure Environment Variables

Create a .env file:

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

4. Start the Service

npx tsx src/index.ts

For complete project configuration (tsconfig.json, package.json, etc.), please refer to the example project.

API Reference

LanggraphAgent

Wraps compiled LangGraph workflow as an AG-UI compatible Agent.

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

const agent = new LanggraphAgent({
  compiledWorkflow: compiledGraph,  // Return value of StateGraph.compile()
});

Constructor Parameters:

Parameter	Type	Description
compiledWorkflow	CompiledStateGraph	Compiled LangGraph workflow

ClientStateAnnotation

Predefined state annotation containing client tools and message history. Used to build LangGraph workflows that support the AG-UI protocol.

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

const workflow = new StateGraph(ClientStateAnnotation)
  .addNode("chat_node", async (state: ClientState) => {
    // state.messages - message history
    // state.client.tools - tools passed from client
  });

ClientState

TypeScript type corresponding to ClientStateAnnotation. Used to define the parameter type of node functions, allowing you to access message history and client tools within nodes.

async function chatNode(state: ClientState, config?: RunnableConfig) {
  // Access message history
  const messages = state.messages;

  // Access tools passed from client
  const tools = state.client?.tools || [];

  // ...
}

Field Descriptions:

Field	Type	Description
messages	BaseMessage[]	Message history (from LangGraph's MessagesAnnotation)
client.tools	Tool[]	Tool list passed from frontend client

Related Resources

• Complete Example Code
• LangGraph Official Documentation
• AG-UI Protocol