Skip to main content

​
Overview

The LanggraphAgent integrates AG-Kit with LangGraph workflows. It streams execution events, maps AG-UI messages to LangGraph messages, exposes AG-Kit tools to LangGraph via state.agKit.actions, and supports checkpointing (in-memory or TDAI-backed).

​
Installation

pnpm add @ag-kit/agents @ag-kit/adapter-langgraph @langchain/langgraph
Optional:
  • @langchain/openai – if you use OpenAI models (e.g., ChatOpenAI in examples)

​
Exports

All exports are available from @ag-kit/adapter-langgraph:
  • LanggraphAgent - Main agent class for LangGraph integration
  • AGKitStateAnnotation - State annotation for LangGraph workflows
  • AGKitPropertiesAnnotation - Properties annotation containing AG-Kit actions
  • type AGKitState - TypeScript type for the AG-Kit state structure
  • TDAISaver - Checkpoint saver implementation using TDAI Memory
  • type TDAISaverConfig - Configuration type for TDAISaver

​
Quick start

import { LanggraphAgent, AGKitStateAnnotation } from "@ag-kit/adapter-langgraph";
import { StateGraph, Command, START, END, MemorySaver } from "@langchain/langgraph";
import type { AGKitState } from "@ag-kit/adapter-langgraph";

const workflow = new StateGraph(AGKitStateAnnotation)
  .addNode("chat_node", async (state: AGKitState) => {
    // Produce a response and append to messages
    const response = { 
      role: "assistant", 
      content: "Hello from LangGraph!" 
    };
    return new Command({ 
      goto: END, 
      update: { messages: [response] } 
    });
  })
  .addEdge(START, "chat_node")
  .addEdge("chat_node", END);

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

const agent = new LanggraphAgent({
  name: "langgraph-agent",
  description: "A LangGraph workflow agent",
  compiledWorkflow,
});

​
Server integration

Pass the agent to the server. The server exposes a POST /send-message SSE endpoint. 
import { run } from "@ag-kit/server";

run({ 
  createAgent: () => ({ agent: myAgent }),
  port: 3000 
});

​
Using AG-Kit Tools in Workflows

AG-Kit tools are automatically exposed to your LangGraph workflow via state.agKit.actions. You can access these tools in your workflow nodes: 
import { AGKitStateAnnotation, type AGKitState } from "@ag-kit/adapter-langgraph";
import { StateGraph, Command, START, END } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { DynamicStructuredTool } from "@langchain/core/tools";

const workflow = new StateGraph(AGKitStateAnnotation)
  .addNode("agent", async (state: AGKitState) => {
    // Access AG-Kit tools from state
    // state.agKit.actions contains the tool definitions passed to the agent
    const agKitActions = state.agKit.actions || [];
    
    // Convert AG-Kit actions to LangChain tools if needed
    const tools = agKitActions.map(action => 
      new DynamicStructuredTool({
        name: action.name,
        description: action.description,
        schema: action.schema, // Should be a Zod schema
        func: async () => "" // Tool handler should be implemented
      })
    );
    
    const model = new ChatOpenAI({ modelName: "gpt-4" });
    const response = await model.bindTools(tools).invoke(state.messages);
    
    return new Command({
      update: { messages: [response] }
    });
  })
  .addEdge(START, "agent")
  .addEdge("agent", END);
Note: The state.agKit.actions array contains tool definitions that are automatically populated from the tools passed to agent.run(). These are already converted to a format compatible with LangGraph workflows.

​
Checkpointing

The LanggraphAgent supports checkpointing for state persistence. You can use in-memory checkpointing or TDAI-backed checkpointing: In-memory checkpointing: 
import { MemorySaver } from "@langchain/langgraph";

const compiledWorkflow = workflow.compile({
  checkpointer: new MemorySaver()
});
TDAI-backed checkpointing: 
import { TDAISaver } from "@ag-kit/adapter-langgraph";

const saver = new TDAISaver({
  // TDAI Memory configuration
  // See TDAISaverConfig for available options
});

const compiledWorkflow = workflow.compile({
  checkpointer: saver
});

​
API

​
class LanggraphAgent

The LanggraphAgent class integrates AG-Kit with LangGraph workflows, providing event streaming, message mapping, and tool exposure. 
new LanggraphAgent(config: AgentConfig & {
  compiledWorkflow: CompiledWorkflow;
})
​
name
string
required
Unique identifier for the agent.
​
description
string
Human-readable description of the agent.
​
compiledWorkflow
CompiledWorkflow
required
Compiled LangGraph workflow to execute. Typically created via workflow.compile(…). Must use AGKitStateAnnotation as the state schema.

​
Methods

run()
run(input: RunAgentInput): Observable<BaseEvent>
Executes the LangGraph workflow and emits BaseEvent values from @ag-ui/client during execution. Parameters:
  • input - RunAgentInput object containing messages, run ID, thread ID, tools, and other configuration
Returns:
  • Observable<BaseEvent> - RxJS Observable that emits execution events
Example: 
import { RunAgentInput } from "@ag-ui/client";

const input: RunAgentInput = {
  messages: [{ role: "user", content: "Hello" }],
  runId: "run-123",
  threadId: "thread-456",
  tools: [/* tool definitions */],
  state: {},
  context: [],
  forwardedProps: {}
};

agent.run(input).subscribe(event => {
  console.log("Event:", event.type);
});

​
Event types

The agent emits the following event types during execution:
  • RUN_STARTED - Emitted when execution begins
  • RUN_FINISHED - Emitted when execution completes (may include outcome: 'interrupt' and interrupt payload for interrupted runs)
  • RUN_ERROR - Emitted when an error occurs during execution
  • TEXT_MESSAGE_START - Emitted when a text message begins
  • TEXT_MESSAGE_CONTENT - Emitted for each chunk of message content (supports streaming)
  • TEXT_MESSAGE_END - Emitted when a text message completes
  • TOOL_CALL_START - Emitted when a tool call begins
  • TOOL_CALL_ARGS - Emitted for tool call arguments (supports streaming deltas)
  • TOOL_CALL_END - Emitted when a tool call completes
  • TOOL_CALL_RESULT - Emitted with the result of a tool call
Tip: In most applications you don’t need to handle these events directly. @ag-kit/server consumes them from the agent and streams them over SSE for you.

​
AGKitStateAnnotation

The AGKitStateAnnotation provides the state schema for LangGraph workflows. It includes:
  • messages - Array of LangGraph messages
  • agKit.actions - Array of AG-Kit tools exposed to the workflow
Usage: 
import { AGKitStateAnnotation, type AGKitState } from "@ag-kit/adapter-langgraph";
import { StateGraph } from "@langchain/langgraph";

const workflow = new StateGraph(AGKitStateAnnotation)
  .addNode("node", async (state: AGKitState) => {
    // Access messages and AG-Kit tools
    const messages = state.messages;
    const tools = state.agKit.actions;
    // ...
  });

​
TDAISaver

The TDAISaver class provides checkpoint persistence using TDAI Memory storage. 
new TDAISaver(config: TDAISaverConfig)
​
checkpointType
string
Collection name for storing checkpoints. Default: “checkpoints”
​
checkpointWritesType
string
Collection name for storing checkpoint writes. Default: “checkpoint_writes”
​
...IMemoryClientOptions
object
Additional TDAI Memory client configuration options. See TDAI Memory documentation for details.
Example: 
import { TDAISaver } from "@ag-kit/adapter-langgraph";

const saver = new TDAISaver({
  checkpointType: "my_checkpoints",
  // TDAI Memory configuration
});

const compiledWorkflow = workflow.compile({
  checkpointer: saver
});

​
Best Practices

  1. Use AGKitStateAnnotation: Always use AGKitStateAnnotation as your state schema to enable AG-Kit integration
  2. Access Tools from State: Use state.agKit.actions to access AG-Kit tools in your workflow nodes
  3. Checkpointing: Use checkpointing for state persistence in production applications
  4. Error Handling: Handle RUN_ERROR events appropriately in your application
  5. Streaming: Leverage event streaming for real-time user feedback

​
See also