or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assistants.mdauth.mdclient.mdcrons.mdindex.mdreact.mdruns.mdstore.mdthreads.md
tile.json

tessl/npm-langchain--langgraph-sdk

TypeScript/JavaScript SDK for interacting with the LangGraph REST API server

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@langchain/langgraph-sdk@0.0.x

To install, run

npx @tessl/cli install tessl/npm-langchain--langgraph-sdk@0.0.0

index.mddocs/

LangGraph SDK

The LangGraph SDK is a TypeScript/JavaScript client library for interacting with the LangGraph REST API server. It enables developers to build applications that can manage assistants, threads, and runs in LangGraph applications. The SDK offers comprehensive client functionality with methods for creating and managing conversational threads, streaming responses from LangGraph agents, handling authentication, and integrating with React applications.

Package Information

  • Package Name: @langchain/langgraph-sdk
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @langchain/langgraph-sdk

Core Imports

import { Client } from "@langchain/langgraph-sdk";

For specific functionality using dedicated export paths:

import { Client, getApiKey } from "@langchain/langgraph-sdk";
import { Client } from "@langchain/langgraph-sdk/client";
import { Auth, HTTPException } from "@langchain/langgraph-sdk/auth";
import { useStream } from "@langchain/langgraph-sdk/react";
import { LoadExternalComponent, useStreamContext, experimental_loadShare } from "@langchain/langgraph-sdk/react-ui";
import { typedUi } from "@langchain/langgraph-sdk/react-ui/server";

CommonJS:

const { Client, getApiKey } = require("@langchain/langgraph-sdk");
const { Auth } = require("@langchain/langgraph-sdk/auth");
const { useStream } = require("@langchain/langgraph-sdk/react");

Basic Usage

import { Client } from "@langchain/langgraph-sdk";

// Create client with API key
const client = new Client({
  apiUrl: "https://api.langgraph.example.com",
  apiKey: "your-api-key"
});

// Create a thread
const thread = await client.threads.create({
  metadata: { user_id: "user123" }
});

// Stream a run
for await (const chunk of client.runs.stream(
  thread.thread_id,
  "assistant-id",
  { input: { message: "Hello!" } }
)) {
  console.log(chunk.event, chunk.data);
}

Architecture

The LangGraph SDK is built around several key components:

  • Client Architecture: Main Client class providing access to specialized clients for different resources
  • Resource Clients: Dedicated clients for assistants, threads, runs, crons, and store operations
  • Streaming Support: Real-time streaming of run execution with various stream modes
  • Type Safety: Full TypeScript integration with generic types for state management
  • React Integration: Hooks and UI components for building interactive LangGraph applications
  • Authentication: Flexible auth system supporting custom authentication workflows

Capabilities

Core Client API

Main client class and configuration for connecting to LangGraph API servers. Provides centralized access to all LangGraph resources and handles authentication, request management, and base configuration.

class Client<TStateType = DefaultValues, TUpdateType = TStateType, TCustomEventType = unknown> {
  assistants: AssistantsClient;
  threads: ThreadsClient<TStateType, TUpdateType>;
  runs: RunsClient<TStateType, TUpdateType, TCustomEventType>;
  crons: CronsClient;
  store: StoreClient;
  constructor(config?: ClientConfig);
}

interface ClientConfig {
  apiUrl?: string;
  apiKey?: string;
  callerOptions?: AsyncCallerParams;
  timeoutMs?: number;
  defaultHeaders?: Record<string, string>;
  onRequest?: RequestHook;
}

function getApiKey(apiKey?: string): string | undefined;

Core Client API

Assistants Management

Comprehensive assistant management for creating, configuring, and managing LangGraph assistants. Includes graph inspection, schema management, and version control.

interface AssistantsClient {
  get(assistantId: string): Promise<Assistant>;
  create(payload: CreateAssistantPayload): Promise<Assistant>;
  update(assistantId: string, payload: UpdateAssistantPayload): Promise<Assistant>;
  delete(assistantId: string): Promise<void>;
  getGraph(assistantId: string, options?: { xray?: boolean | number }): Promise<AssistantGraph>;
  getSchemas(assistantId: string): Promise<GraphSchema>;
}

Assistants Management

Threads Management

Thread lifecycle management for conversation handling, state management, and history tracking. Supports thread creation, copying, state updates, and comprehensive search functionality.

interface ThreadsClient<TStateType, TUpdateType> {
  get<ValuesType = TStateType>(threadId: string): Promise<Thread<ValuesType>>;
  create(payload?: CreateThreadPayload): Promise<Thread<TStateType>>;
  getState<ValuesType = TStateType>(
    threadId: string,
    checkpoint?: Checkpoint | string,
    options?: { subgraphs?: boolean }
  ): Promise<ThreadState<ValuesType>>;
  updateState<ValuesType = TUpdateType>(
    threadId: string,
    options: UpdateStateOptions
  ): Promise<Pick<Config, "configurable">>;
}

Threads Management

Runs Management and Streaming

Execute and monitor LangGraph runs with comprehensive streaming support. Includes real-time execution streaming, batch processing, run lifecycle management, and flexible stream modes.

interface RunsClient<TStateType, TUpdateType, TCustomEventType> {
  stream(
    threadId: string | null,
    assistantId: string,
    payload?: RunsStreamPayload
  ): TypedAsyncGenerator<TStreamMode, TSubgraphs, TStateType, TUpdateType, TCustomEventType>;

  create(threadId: string, assistantId: string, payload?: RunsCreatePayload): Promise<Run>;
  wait(threadId: string | null, assistantId: string, payload?: RunsWaitPayload): Promise<ThreadState["values"]>;
  joinStream(threadId: string | null, runId: string, options?: JoinStreamOptions): AsyncGenerator;
}

Runs Management and Streaming

Scheduled Jobs

Cron job management for scheduling recurring LangGraph runs. Supports thread-specific and standalone cron jobs with flexible scheduling options.

interface CronsClient {
  create(assistantId: string, payload?: CronsCreatePayload): Promise<CronCreateResponse>;
  createForThread(threadId: string, assistantId: string, payload?: CronsCreatePayload): Promise<CronCreateForThreadResponse>;
  delete(cronId: string): Promise<void>;
  search(query?: CronSearchQuery): Promise<Cron[]>;
}

Scheduled Jobs

Key-Value Store

Distributed key-value store operations with namespace support, TTL management, and search capabilities. Perfect for persistent data storage and retrieval across LangGraph applications.

interface StoreClient {
  putItem(
    namespace: string[],
    key: string,
    value: Record<string, unknown>,
    options?: { index?: false | string[] | null; ttl?: number | null }
  ): Promise<void>;

  getItem(
    namespace: string[],
    key: string,
    options?: { refreshTtl?: boolean | null }
  ): Promise<Item | null>;

  searchItems(
    namespacePrefix: string[],
    options?: SearchItemsOptions
  ): Promise<SearchItemsResponse>;
}

Key-Value Store

Authentication

Flexible authentication system supporting custom authentication workflows, event handling, and HTTP exception management for secure LangGraph applications.

class Auth<TExtra = {}, TAuthReturn extends BaseAuthReturn = BaseAuthReturn, TUser extends BaseUser = ToUserLike<TAuthReturn>> {
  authenticate<T extends BaseAuthReturn>(cb: AuthenticateCallback<T>): Auth<TExtra, T>;
  on<T extends CallbackEvent>(event: T, callback: OnCallback<T, TUser>): this;
}

class HTTPException {
  constructor(message: string, status: number);
}

Authentication

React Integration

React hooks and UI components for building interactive LangGraph applications. Includes streaming hooks, UI component loading, and complete React state management.

function useStream<StateType, Bag>(options: UseStreamOptions): UseStream<StateType, Bag>;

function LoadExternalComponent(props: {
  stream: UseStream;
  message: UIMessage;
  namespace?: string;
  meta?: any;
  fallback?: React.ComponentType;
}): React.ReactElement;

React Integration

React UI Components

React UI components for loading external components and managing UI state in LangGraph streaming applications. Includes context management and server-side utilities.

function LoadExternalComponent(props: {
  stream: UseStream;
  message: UIMessage;
  namespace?: string;
  meta?: any;
  fallback?: React.ComponentType;
}): React.ReactElement;

function useStreamContext(): UseStream | undefined;

interface UIMessage {
  type: "ui";
  id: string;
  component: string;
  props?: Record<string, unknown>;
}

React UI Components

Core Types

Essential Interfaces

interface Assistant {
  assistant_id: string;
  graph_id: string;
  config: Config;
  created_at: string;
  updated_at: string;
  name?: string;
  description?: string;
}

interface Thread<ValuesType = DefaultValues> {
  thread_id: string;
  created_at: string;
  updated_at: string;
  metadata: Metadata;
  status: ThreadStatus;
  values: ValuesType;
}

interface Run {
  run_id: string;
  thread_id: string;
  assistant_id: string;
  created_at: string;
  updated_at: string;
  status: RunStatus;
  metadata: Metadata;
}

interface Config {
  tags?: string[];
  recursion_limit?: number;
  configurable?: {
    thread_id?: string | null | undefined;
    checkpoint_id?: string | null | undefined;
    [key: string]: unknown;
  };
}

Message Types

interface BaseMessage {
  id?: string;
  type: string;
  content: MessageContent;
  additional_kwargs?: MessageAdditionalKwargs;
  response_metadata?: Record<string, any>;
}

interface HumanMessage extends BaseMessage {
  type: "human";
}

interface AIMessage extends BaseMessage {
  type: "ai";
  tool_calls?: ToolCall[];
  invalid_tool_calls?: InvalidToolCall[];
  usage_metadata?: UsageMetadata;
}

interface ToolMessage extends BaseMessage {
  type: "tool";
  tool_call_id: string;
}

type Message = HumanMessage | AIMessage | ToolMessage | SystemMessage | FunctionMessage | RemoveMessage;

Stream Types

type StreamMode =
  | "values"
  | "updates"
  | "messages"
  | "events"
  | "debug"
  | "metadata"
  | "custom";

interface ValuesStreamEvent<ValuesType = DefaultValues> {
  event: "values";
  data: ValuesType;
}

interface UpdatesStreamEvent<UpdateType = DefaultValues> {
  event: "updates";
  data: Record<string, UpdateType>;
}

interface MessagesStreamEvent {
  event: "messages";
  data: Message[];
}

Status Enums

type RunStatus = "pending" | "running" | "error" | "success" | "timeout" | "interrupted";

type ThreadStatus = "idle" | "busy" | "interrupted" | "error";

type OnConflictBehavior = "raise" | "do_nothing";

type MultitaskStrategy = "reject" | "interrupt" | "rollback" | "enqueue";

type OnCompletionBehavior = "complete" | "continue";

type DisconnectMode = "cancel" | "continue";

type CancelAction = "interrupt" | "rollback";

type AssistantSortBy = "assistant_id" | "graph_id" | "name" | "created_at" | "updated_at";

type ThreadSortBy = "thread_id" | "status" | "created_at" | "updated_at";

type CronSortBy = "cron_id" | "assistant_id" | "thread_id" | "created_at" | "updated_at" | "next_run_date";

type SortOrder = "asc" | "desc";