0
# Assistants Management
1

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

4
## Capabilities
5

6
### Get Assistant
7

8
Retrieve assistant information by ID.
9

10
```typescript { .api }
11
/**
12
 * Get an assistant by ID
13
 * @param assistantId - The ID of the assistant
14
 * @returns Assistant configuration and metadata
15
 */
16
get(assistantId: string): Promise<Assistant>;
17

18
interface Assistant {
19
  /** The ID of the assistant */
20
  assistant_id: string;
21
  /** The ID of the graph */
22
  graph_id: string;
23
  /** Assistant configuration */
24
  config: Config;
25
  /** Creation timestamp */
26
  created_at: string;
27
  /** Last update timestamp */
28
  updated_at: string;
29
  /** Optional assistant name */
30
  name?: string;
31
  /** Optional assistant description */
32
  description?: string;
33
  /** Additional metadata */
34
  metadata?: Metadata;
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
const assistant = await client.assistants.get("assistant-123");
42
console.log(`Assistant: ${assistant.name}`);
43
console.log(`Graph ID: ${assistant.graph_id}`);
44
console.log(`Created: ${assistant.created_at}`);
45
```
46

47
### Create Assistant
48

49
Create a new assistant with specified configuration.
50

51
```typescript { .api }
52
/**
53
 * Create a new assistant
54
 * @param payload - Assistant creation configuration
55
 * @returns The created assistant
56
 */
57
create(payload: CreateAssistantPayload): Promise<Assistant>;
58

59
interface CreateAssistantPayload {
60
  /** ID of the graph to use for this assistant */
61
  graphId: string;
62
  /** Optional assistant configuration */
63
  config?: Config;
64
  /** Optional metadata for the assistant */
65
  metadata?: Metadata;
66
  /** Optional specific assistant ID (if not provided, will be generated) */
67
  assistantId?: string;
68
  /** Behavior when assistant with same ID already exists */
69
  ifExists?: OnConflictBehavior;
70
  /** Optional name for the assistant */
71
  name?: string;
72
  /** Optional description */
73
  description?: string;
74
}
75

76
type OnConflictBehavior = "raise" | "do_nothing";
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
// Create assistant with minimal configuration
83
const assistant = await client.assistants.create({
84
  graphId: "my-graph-id",
85
  name: "My Assistant",
86
  description: "Helpful AI assistant"
87
});
88

89
// Create assistant with custom configuration
90
const assistant = await client.assistants.create({
91
  graphId: "my-graph-id",
92
  assistantId: "custom-assistant-id",
93
  config: {
94
    recursion_limit: 50,
95
    configurable: {
96
      model: "gpt-4",
97
      temperature: 0.7
98
    }
99
  },
100
  metadata: {
101
    team: "ai-team",
102
    version: "1.0"
103
  },
104
  ifExists: "do_nothing"
105
});
106
```
107

108
### Update Assistant
109

110
Update an existing assistant's configuration or metadata.
111

112
```typescript { .api }
113
/**
114
 * Update an assistant
115
 * @param assistantId - ID of the assistant to update
116
 * @param payload - Update configuration
117
 * @returns The updated assistant
118
 */
119
update(assistantId: string, payload: UpdateAssistantPayload): Promise<Assistant>;
120

121
interface UpdateAssistantPayload {
122
  /** New graph ID (optional) */
123
  graphId?: string;
124
  /** Updated configuration (optional) */
125
  config?: Config;
126
  /** Updated metadata (optional) */
127
  metadata?: Metadata;
128
  /** Updated name (optional) */
129
  name?: string;
130
  /** Updated description (optional) */
131
  description?: string;
132
}
133
```
134

135
**Usage Examples:**
136

137
```typescript
138
// Update assistant name and description
139
const updated = await client.assistants.update("assistant-123", {
140
  name: "Updated Assistant Name",
141
  description: "Updated description"
142
});
143

144
// Update configuration
145
const updated = await client.assistants.update("assistant-123", {
146
  config: {
147
    recursion_limit: 100,
148
    configurable: {
149
      model: "gpt-4-turbo",
150
      temperature: 0.8
151
    }
152
  }
153
});
154
```
155

156
### Delete Assistant
157

158
Remove an assistant permanently.
159

160
```typescript { .api }
161
/**
162
 * Delete an assistant
163
 * @param assistantId - ID of the assistant to delete
164
 */
165
delete(assistantId: string): Promise<void>;
166
```
167

168
**Usage Examples:**
169

170
```typescript
171
await client.assistants.delete("assistant-123");
172
console.log("Assistant deleted successfully");
173
```
174

175
### Search Assistants
176

177
Search and list assistants with filtering options.
178

179
```typescript { .api }
180
/**
181
 * Search assistants with optional filtering
182
 * @param query - Search criteria and pagination options
183
 * @returns List of matching assistants
184
 */
185
search(query?: AssistantSearchQuery): Promise<Assistant[]>;
186

187
interface AssistantSearchQuery {
188
  /** Filter by graph ID */
189
  graphId?: string;
190
  /** Filter by metadata */
191
  metadata?: Metadata;
192
  /** Maximum number of results (default: 10) */
193
  limit?: number;
194
  /** Number of results to skip (default: 0) */
195
  offset?: number;
196
  /** Sort field */
197
  sortBy?: AssistantSortBy;
198
  /** Sort order */
199
  sortOrder?: SortOrder;
200
}
201

202
type AssistantSortBy = "created_at" | "updated_at" | "name";
203
type SortOrder = "asc" | "desc";
204
```
205

206
**Usage Examples:**
207

208
```typescript
209
// Get all assistants
210
const allAssistants = await client.assistants.search();
211

212
// Search with filters
213
const assistants = await client.assistants.search({
214
  graphId: "my-graph-id",
215
  limit: 20,
216
  sortBy: "created_at",
217
  sortOrder: "desc"
218
});
219

220
// Search by metadata
221
const teamAssistants = await client.assistants.search({
222
  metadata: { team: "ai-team" },
223
  limit: 50
224
});
225
```
226

227
### Get Assistant Graph
228

229
Retrieve the graph representation of an assistant.
230

231
```typescript { .api }
232
/**
233
 * Get the JSON representation of the graph assigned to an assistant
234
 * @param assistantId - The ID of the assistant
235
 * @param options - Graph retrieval options
236
 * @returns Serialized graph representation
237
 */
238
getGraph(assistantId: string, options?: GraphOptions): Promise<AssistantGraph>;
239

240
interface GraphOptions {
241
  /** Whether to include subgraphs in the serialized representation.
242
   * If a number, only subgraphs with depth <= value are included */
243
  xray?: boolean | number;
244
}
245

246
interface AssistantGraph {
247
  /** Graph nodes and their connections */
248
  nodes: GraphNode[];
249
  /** Graph edges defining flow */
250
  edges: GraphEdge[];
251
  /** Graph metadata */
252
  metadata?: Record<string, any>;
253
}
254
```
255

256
**Usage Examples:**
257

258
```typescript
259
// Get basic graph structure
260
const graph = await client.assistants.getGraph("assistant-123");
261
console.log(`Graph has ${graph.nodes.length} nodes`);
262

263
// Get graph with subgraph details
264
const detailedGraph = await client.assistants.getGraph("assistant-123", {
265
  xray: true
266
});
267

268
// Get graph with limited subgraph depth
269
const limitedGraph = await client.assistants.getGraph("assistant-123", {
270
  xray: 2 // Only include subgraphs up to depth 2
271
});
272
```
273

274
### Get Assistant Schemas
275

276
Retrieve the state and config schemas of the assistant's graph.
277

278
```typescript { .api }
279
/**
280
 * Get the state and config schema of the graph assigned to an assistant
281
 * @param assistantId - The ID of the assistant
282
 * @returns Graph schema with JSON schemas for input, output, state, and config
283
 */
284
getSchemas(assistantId: string): Promise<GraphSchema>;
285

286
interface GraphSchema {
287
  /** The ID of the graph */
288
  graph_id: string;
289
  /** Schema for input state (JSON Schema format) */
290
  input_schema?: JSONSchema7 | null;
291
  /** Schema for output state (JSON Schema format) */
292
  output_schema?: JSONSchema7 | null;
293
  /** Schema for graph state (JSON Schema format) */
294
  state_schema?: JSONSchema7 | null;
295
  /** Schema for graph config (JSON Schema format) */
296
  config_schema?: JSONSchema7 | null;
297
}
298
```
299

300
**Usage Examples:**
301

302
```typescript
303
const schemas = await client.assistants.getSchemas("assistant-123");
304

305
if (schemas.input_schema) {
306
  console.log("Input schema:", JSON.stringify(schemas.input_schema, null, 2));
307
}
308

309
if (schemas.state_schema) {
310
  console.log("State schema:", JSON.stringify(schemas.state_schema, null, 2));
311
}
312
```
313

314
### Get Assistant Subgraphs
315

316
Retrieve subgraph information for complex assistants.
317

318
```typescript { .api }
319
/**
320
 * Get the subgraphs of an assistant
321
 * @param assistantId - The ID of the assistant
322
 * @param options - Subgraph retrieval options
323
 * @returns The subgraphs of the assistant
324
 */
325
getSubgraphs(assistantId: string, options?: SubgraphOptions): Promise<Subgraphs>;
326

327
interface SubgraphOptions {
328
  /** Specific namespace to retrieve */
329
  namespace?: string;
330
  /** Whether to recursively include nested subgraphs */
331
  recurse?: boolean;
332
}
333

334
type Subgraphs = Record<string, GraphSchema>;
335
```
336

337
**Usage Examples:**
338

339
```typescript
340
// Get all subgraphs
341
const subgraphs = await client.assistants.getSubgraphs("assistant-123");
342
console.log("Available subgraphs:", Object.keys(subgraphs));
343

344
// Get specific namespace
345
const authSubgraph = await client.assistants.getSubgraphs("assistant-123", {
346
  namespace: "auth"
347
});
348

349
// Get with recursive expansion
350
const allSubgraphs = await client.assistants.getSubgraphs("assistant-123", {
351
  recurse: true
352
});
353
```
354

355
### Version Management
356

357
Manage assistant versions for deployment and rollback scenarios.
358

359
```typescript { .api }
360
/**
361
 * List all versions of an assistant
362
 * @param assistantId - ID of the assistant
363
 * @param payload - Version listing options
364
 * @returns List of assistant versions
365
 */
366
getVersions(assistantId: string, payload?: GetVersionsPayload): Promise<AssistantVersion[]>;
367

368
/**
369
 * Change the active version of an assistant
370
 * @param assistantId - ID of the assistant
371
 * @param version - The version number to set as latest
372
 * @returns The updated assistant
373
 */
374
setLatest(assistantId: string, version: number): Promise<Assistant>;
375

376
interface GetVersionsPayload {
377
  /** Filter by metadata */
378
  metadata?: Metadata;
379
  /** Maximum number of versions to return (default: 10) */
380
  limit?: number;
381
  /** Number of versions to skip (default: 0) */
382
  offset?: number;
383
}
384

385
interface AssistantVersion {
386
  /** Version number */
387
  version: number;
388
  /** Assistant ID */
389
  assistant_id: string;
390
  /** Graph ID for this version */
391
  graph_id: string;
392
  /** Configuration for this version */
393
  config: Config;
394
  /** Version creation timestamp */
395
  created_at: string;
396
  /** Version metadata */
397
  metadata?: Metadata;
398
}
399
```
400

401
**Usage Examples:**
402

403
```typescript
404
// Get all versions
405
const versions = await client.assistants.getVersions("assistant-123");
406
console.log(`Assistant has ${versions.length} versions`);
407

408
// Get recent versions
409
const recentVersions = await client.assistants.getVersions("assistant-123", {
410
  limit: 5
411
});
412

413
// Set specific version as latest
414
await client.assistants.setLatest("assistant-123", 3);
415

416
// Rollback to previous version
417
const versions = await client.assistants.getVersions("assistant-123", { limit: 2 });
418
if (versions.length > 1) {
419
  await client.assistants.setLatest("assistant-123", versions[1].version);
420
}
421
```
422

423
## Common Types
424

425
### Configuration Types
426

427
```typescript { .api }
428
interface Config {
429
  /** Tags for this assistant and any sub-calls */
430
  tags?: string[];
431
  /** Maximum number of times a call can recurse (default: 25) */
432
  recursion_limit?: number;
433
  /** Runtime values for configurable attributes */
434
  configurable?: {
435
    /** ID of the thread */
436
    thread_id?: string | null;
437
    /** Timestamp of the state checkpoint */
438
    checkpoint_id?: string | null;
439
    [key: string]: unknown;
440
  };
441
}
442

443
type Metadata = {
444
  source?: "input" | "loop" | "update" | string;
445
  step?: number;
446
  writes?: Record<string, unknown> | null;
447
  parents?: Record<string, string>;
448
  [key: string]: unknown;
449
} | null | undefined;
450
```
451

452
## Error Handling
453

454
Assistant operations can throw various errors that should be handled appropriately:
455

456
```typescript
457
try {
458
  const assistant = await client.assistants.get("nonexistent-id");
459
} catch (error) {
460
  if (error.status === 404) {
461
    console.error("Assistant not found");
462
  } else if (error.status === 403) {
463
    console.error("Access denied");
464
  } else {
465
    console.error("Unexpected error:", error.message);
466
  }
467
}
468
```