0
# LangGraph SDK
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: @langchain/langgraph-sdk
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @langchain/langgraph-sdk`
10
11
## Core Imports
12
13
```typescript
14
import { Client } from "@langchain/langgraph-sdk";
15
```
16
17
For specific functionality using dedicated export paths:
18
19
```typescript
20
import { Client, getApiKey } from "@langchain/langgraph-sdk";
21
import { Client } from "@langchain/langgraph-sdk/client";
22
import { Auth, HTTPException } from "@langchain/langgraph-sdk/auth";
23
import { useStream } from "@langchain/langgraph-sdk/react";
24
import { LoadExternalComponent, useStreamContext, experimental_loadShare } from "@langchain/langgraph-sdk/react-ui";
25
import { typedUi } from "@langchain/langgraph-sdk/react-ui/server";
26
```
27
28
CommonJS:
29
30
```javascript
31
const { Client, getApiKey } = require("@langchain/langgraph-sdk");
32
const { Auth } = require("@langchain/langgraph-sdk/auth");
33
const { useStream } = require("@langchain/langgraph-sdk/react");
34
```
35
36
## Basic Usage
37
38
```typescript
39
import { Client } from "@langchain/langgraph-sdk";
40
41
// Create client with API key
42
const client = new Client({
43
apiUrl: "https://api.langgraph.example.com",
44
apiKey: "your-api-key"
45
});
46
47
// Create a thread
48
const thread = await client.threads.create({
49
metadata: { user_id: "user123" }
50
});
51
52
// Stream a run
53
for await (const chunk of client.runs.stream(
54
thread.thread_id,
55
"assistant-id",
56
{ input: { message: "Hello!" } }
57
)) {
58
console.log(chunk.event, chunk.data);
59
}
60
```
61
62
## Architecture
63
64
The LangGraph SDK is built around several key components:
65
66
- **Client Architecture**: Main `Client` class providing access to specialized clients for different resources
67
- **Resource Clients**: Dedicated clients for assistants, threads, runs, crons, and store operations
68
- **Streaming Support**: Real-time streaming of run execution with various stream modes
69
- **Type Safety**: Full TypeScript integration with generic types for state management
70
- **React Integration**: Hooks and UI components for building interactive LangGraph applications
71
- **Authentication**: Flexible auth system supporting custom authentication workflows
72
73
## Capabilities
74
75
### Core Client API
76
77
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.
78
79
```typescript { .api }
80
class Client<TStateType = DefaultValues, TUpdateType = TStateType, TCustomEventType = unknown> {
81
assistants: AssistantsClient;
82
threads: ThreadsClient<TStateType, TUpdateType>;
83
runs: RunsClient<TStateType, TUpdateType, TCustomEventType>;
84
crons: CronsClient;
85
store: StoreClient;
86
constructor(config?: ClientConfig);
87
}
88
89
interface ClientConfig {
90
apiUrl?: string;
91
apiKey?: string;
92
callerOptions?: AsyncCallerParams;
93
timeoutMs?: number;
94
defaultHeaders?: Record<string, string>;
95
onRequest?: RequestHook;
96
}
97
98
function getApiKey(apiKey?: string): string | undefined;
99
```
100
101
[Core Client API](./client.md)
102
103
### Assistants Management
104
105
Comprehensive assistant management for creating, configuring, and managing LangGraph assistants. Includes graph inspection, schema management, and version control.
106
107
```typescript { .api }
108
interface AssistantsClient {
109
get(assistantId: string): Promise<Assistant>;
110
create(payload: CreateAssistantPayload): Promise<Assistant>;
111
update(assistantId: string, payload: UpdateAssistantPayload): Promise<Assistant>;
112
delete(assistantId: string): Promise<void>;
113
getGraph(assistantId: string, options?: { xray?: boolean | number }): Promise<AssistantGraph>;
114
getSchemas(assistantId: string): Promise<GraphSchema>;
115
}
116
```
117
118
[Assistants Management](./assistants.md)
119
120
### Threads Management
121
122
Thread lifecycle management for conversation handling, state management, and history tracking. Supports thread creation, copying, state updates, and comprehensive search functionality.
123
124
```typescript { .api }
125
interface ThreadsClient<TStateType, TUpdateType> {
126
get<ValuesType = TStateType>(threadId: string): Promise<Thread<ValuesType>>;
127
create(payload?: CreateThreadPayload): Promise<Thread<TStateType>>;
128
getState<ValuesType = TStateType>(
129
threadId: string,
130
checkpoint?: Checkpoint | string,
131
options?: { subgraphs?: boolean }
132
): Promise<ThreadState<ValuesType>>;
133
updateState<ValuesType = TUpdateType>(
134
threadId: string,
135
options: UpdateStateOptions
136
): Promise<Pick<Config, "configurable">>;
137
}
138
```
139
140
[Threads Management](./threads.md)
141
142
### Runs Management and Streaming
143
144
Execute and monitor LangGraph runs with comprehensive streaming support. Includes real-time execution streaming, batch processing, run lifecycle management, and flexible stream modes.
145
146
```typescript { .api }
147
interface RunsClient<TStateType, TUpdateType, TCustomEventType> {
148
stream(
149
threadId: string | null,
150
assistantId: string,
151
payload?: RunsStreamPayload
152
): TypedAsyncGenerator<TStreamMode, TSubgraphs, TStateType, TUpdateType, TCustomEventType>;
153
154
create(threadId: string, assistantId: string, payload?: RunsCreatePayload): Promise<Run>;
155
wait(threadId: string | null, assistantId: string, payload?: RunsWaitPayload): Promise<ThreadState["values"]>;
156
joinStream(threadId: string | null, runId: string, options?: JoinStreamOptions): AsyncGenerator;
157
}
158
```
159
160
[Runs Management and Streaming](./runs.md)
161
162
### Scheduled Jobs
163
164
Cron job management for scheduling recurring LangGraph runs. Supports thread-specific and standalone cron jobs with flexible scheduling options.
165
166
```typescript { .api }
167
interface CronsClient {
168
create(assistantId: string, payload?: CronsCreatePayload): Promise<CronCreateResponse>;
169
createForThread(threadId: string, assistantId: string, payload?: CronsCreatePayload): Promise<CronCreateForThreadResponse>;
170
delete(cronId: string): Promise<void>;
171
search(query?: CronSearchQuery): Promise<Cron[]>;
172
}
173
```
174
175
[Scheduled Jobs](./crons.md)
176
177
### Key-Value Store
178
179
Distributed key-value store operations with namespace support, TTL management, and search capabilities. Perfect for persistent data storage and retrieval across LangGraph applications.
180
181
```typescript { .api }
182
interface StoreClient {
183
putItem(
184
namespace: string[],
185
key: string,
186
value: Record<string, unknown>,
187
options?: { index?: false | string[] | null; ttl?: number | null }
188
): Promise<void>;
189
190
getItem(
191
namespace: string[],
192
key: string,
193
options?: { refreshTtl?: boolean | null }
194
): Promise<Item | null>;
195
196
searchItems(
197
namespacePrefix: string[],
198
options?: SearchItemsOptions
199
): Promise<SearchItemsResponse>;
200
}
201
```
202
203
[Key-Value Store](./store.md)
204
205
### Authentication
206
207
Flexible authentication system supporting custom authentication workflows, event handling, and HTTP exception management for secure LangGraph applications.
208
209
```typescript { .api }
210
class Auth<TExtra = {}, TAuthReturn extends BaseAuthReturn = BaseAuthReturn, TUser extends BaseUser = ToUserLike<TAuthReturn>> {
211
authenticate<T extends BaseAuthReturn>(cb: AuthenticateCallback<T>): Auth<TExtra, T>;
212
on<T extends CallbackEvent>(event: T, callback: OnCallback<T, TUser>): this;
213
}
214
215
class HTTPException {
216
constructor(message: string, status: number);
217
}
218
```
219
220
[Authentication](./auth.md)
221
222
### React Integration
223
224
React hooks and UI components for building interactive LangGraph applications. Includes streaming hooks, UI component loading, and complete React state management.
225
226
```typescript { .api }
227
function useStream<StateType, Bag>(options: UseStreamOptions): UseStream<StateType, Bag>;
228
229
function LoadExternalComponent(props: {
230
stream: UseStream;
231
message: UIMessage;
232
namespace?: string;
233
meta?: any;
234
fallback?: React.ComponentType;
235
}): React.ReactElement;
236
```
237
238
[React Integration](./react.md)
239
240
### React UI Components
241
242
React UI components for loading external components and managing UI state in LangGraph streaming applications. Includes context management and server-side utilities.
243
244
```typescript { .api }
245
function LoadExternalComponent(props: {
246
stream: UseStream;
247
message: UIMessage;
248
namespace?: string;
249
meta?: any;
250
fallback?: React.ComponentType;
251
}): React.ReactElement;
252
253
function useStreamContext(): UseStream | undefined;
254
255
interface UIMessage {
256
type: "ui";
257
id: string;
258
component: string;
259
props?: Record<string, unknown>;
260
}
261
```
262
263
[React UI Components](./react.md)
264
265
## Core Types
266
267
### Essential Interfaces
268
269
```typescript { .api }
270
interface Assistant {
271
assistant_id: string;
272
graph_id: string;
273
config: Config;
274
created_at: string;
275
updated_at: string;
276
name?: string;
277
description?: string;
278
}
279
280
interface Thread<ValuesType = DefaultValues> {
281
thread_id: string;
282
created_at: string;
283
updated_at: string;
284
metadata: Metadata;
285
status: ThreadStatus;
286
values: ValuesType;
287
}
288
289
interface Run {
290
run_id: string;
291
thread_id: string;
292
assistant_id: string;
293
created_at: string;
294
updated_at: string;
295
status: RunStatus;
296
metadata: Metadata;
297
}
298
299
interface Config {
300
tags?: string[];
301
recursion_limit?: number;
302
configurable?: {
303
thread_id?: string | null | undefined;
304
checkpoint_id?: string | null | undefined;
305
[key: string]: unknown;
306
};
307
}
308
```
309
310
### Message Types
311
312
```typescript { .api }
313
interface BaseMessage {
314
id?: string;
315
type: string;
316
content: MessageContent;
317
additional_kwargs?: MessageAdditionalKwargs;
318
response_metadata?: Record<string, any>;
319
}
320
321
interface HumanMessage extends BaseMessage {
322
type: "human";
323
}
324
325
interface AIMessage extends BaseMessage {
326
type: "ai";
327
tool_calls?: ToolCall[];
328
invalid_tool_calls?: InvalidToolCall[];
329
usage_metadata?: UsageMetadata;
330
}
331
332
interface ToolMessage extends BaseMessage {
333
type: "tool";
334
tool_call_id: string;
335
}
336
337
type Message = HumanMessage | AIMessage | ToolMessage | SystemMessage | FunctionMessage | RemoveMessage;
338
```
339
340
### Stream Types
341
342
```typescript { .api }
343
type StreamMode =
344
| "values"
345
| "updates"
346
| "messages"
347
| "events"
348
| "debug"
349
| "metadata"
350
| "custom";
351
352
interface ValuesStreamEvent<ValuesType = DefaultValues> {
353
event: "values";
354
data: ValuesType;
355
}
356
357
interface UpdatesStreamEvent<UpdateType = DefaultValues> {
358
event: "updates";
359
data: Record<string, UpdateType>;
360
}
361
362
interface MessagesStreamEvent {
363
event: "messages";
364
data: Message[];
365
}
366
```
367
368
### Status Enums
369
370
```typescript { .api }
371
type RunStatus = "pending" | "running" | "error" | "success" | "timeout" | "interrupted";
372
373
type ThreadStatus = "idle" | "busy" | "interrupted" | "error";
374
375
type OnConflictBehavior = "raise" | "do_nothing";
376
377
type MultitaskStrategy = "reject" | "interrupt" | "rollback" | "enqueue";
378
379
type OnCompletionBehavior = "complete" | "continue";
380
381
type DisconnectMode = "cancel" | "continue";
382
383
type CancelAction = "interrupt" | "rollback";
384
385
type AssistantSortBy = "assistant_id" | "graph_id" | "name" | "created_at" | "updated_at";
386
387
type ThreadSortBy = "thread_id" | "status" | "created_at" | "updated_at";
388
389
type CronSortBy = "cron_id" | "assistant_id" | "thread_id" | "created_at" | "updated_at" | "next_run_date";
390
391
type SortOrder = "asc" | "desc";
392
```