0
# Assistant Management
1

2
Create, configure, and manage AI assistants based on registered graphs. Assistants serve as the execution engines for conversational workflows, with support for versioning, configuration, and metadata management.
3

4
## Capabilities
5

6
### Assistant CRUD Operations
7

8
Core operations for creating, reading, updating, and deleting assistants with comprehensive configuration and metadata support.
9

10
```python { .api }
11
from collections.abc import Mapping
12
from langgraph_sdk.schema import (
13
    Assistant, AssistantSelectField, Config, Context, Json,
14
    OnConflictBehavior, QueryParamTypes
15
)
16

17
# Via client.assistants
18
async def get(
19
    assistant_id: str,
20
    *,
21
    headers: Mapping[str, str] | None = None,
22
    params: QueryParamTypes | None = None,
23
) -> Assistant:
24
    """
25
    Get an assistant by ID.
26

27
    Args:
28
        assistant_id: The ID of the assistant to get.
29
        headers: Optional custom headers to include with the request.
30
        params: Optional query parameters to include with the request.
31

32
    Returns:
33
        Assistant: Assistant Object.
34
    """
35

36
async def create(
37
    graph_id: str | None,
38
    config: Config | None = None,
39
    *,
40
    context: Context | None = None,
41
    metadata: Json = None,
42
    assistant_id: str | None = None,
43
    if_exists: OnConflictBehavior | None = None,
44
    name: str | None = None,
45
    headers: Mapping[str, str] | None = None,
46
    params: QueryParamTypes | None = None,
47
) -> Assistant:
48
    """
49
    Create a new assistant.
50

51
    Args:
52
        graph_id: The ID of the graph to create an assistant for.
53
        config: Configuration to merge with the assistant.
54
        context: Context to apply when running the assistant.
55
        metadata: Metadata to merge with the assistant.
56
        assistant_id: ID of the assistant. If None, ID will be a UUID.
57
        if_exists: How to handle duplicate creates. Defaults to "create".
58
        name: The name of the assistant. Defaults to Untitled.
59
        headers: Optional custom headers to include with the request.
60
        params: Optional query parameters to include with the request.
61

62
    Returns:
63
        Assistant: The created assistant.
64
    """
65

66
async def update(
67
    assistant_id: str,
68
    *,
69
    graph_id: str | None = None,
70
    config: Config | None = None,
71
    context: Context | None = None,
72
    metadata: Json = None,
73
    name: str | None = None,
74
    headers: Mapping[str, str] | None = None,
75
    description: str | None = None,
76
    params: QueryParamTypes | None = None,
77
) -> Assistant:
78
    """
79
    Update an assistant.
80

81
    Args:
82
        assistant_id: The ID of the assistant to update.
83
        graph_id: The ID of the graph to assign to the assistant.
84
        config: Configuration to merge with the assistant.
85
        context: Context to apply when running the assistant.
86
        metadata: Metadata to merge with the assistant.
87
        name: The name of the assistant.
88
        headers: Optional custom headers to include with the request.
89
        description: The description of the assistant.
90
        params: Optional query parameters to include with the request.
91

92
    Returns:
93
        Assistant: The updated assistant.
94
    """
95

96
async def delete(
97
    assistant_id: str,
98
    *,
99
    headers: Mapping[str, str] | None = None,
100
    params: QueryParamTypes | None = None,
101
) -> None:
102
    """
103
    Delete an assistant.
104

105
    Args:
106
        assistant_id: The assistant ID to delete.
107
        headers: Optional custom headers to include with the request.
108
        params: Optional query parameters to include with the request.
109
    """
110
```
111

112
### Assistant Discovery & Search
113

114
Search and enumerate assistants with filtering, pagination, and sorting capabilities.
115

116
```python { .api }
117
from langgraph_sdk.schema import (
118
    Assistant, AssistantSelectField, AssistantSortBy, SortOrder, Json, QueryParamTypes
119
)
120

121
async def search(
122
    *,
123
    metadata: Json = None,
124
    graph_id: str | None = None,
125
    limit: int = 10,
126
    offset: int = 0,
127
    sort_by: AssistantSortBy | None = None,
128
    sort_order: SortOrder | None = None,
129
    select: list[AssistantSelectField] | None = None,
130
    headers: Mapping[str, str] | None = None,
131
    params: QueryParamTypes | None = None,
132
) -> list[Assistant]:
133
    """
134
    List assistants from the store.
135

136
    Args:
137
        metadata: Metadata to filter by. Exact match filter for each KV pair.
138
        graph_id: ID of a graph to filter by.
139
        limit: Limit the number of assistants to return.
140
        offset: Offset to start from.
141
        sort_by: Field to sort by. Options are "created_at" and "updated_at".
142
        sort_order: Order to sort by. Options are "asc" and "desc".
143
        select: Fields to include in the response.
144
        headers: Optional custom headers to include with the request.
145
        params: Optional query parameters to include with the request.
146

147
    Returns:
148
        list[Assistant]: List of assistants.
149
    """
150

151
async def count(
152
    *,
153
    metadata: Json = None,
154
    graph_id: str | None = None,
155
    headers: Mapping[str, str] | None = None,
156
    params: QueryParamTypes | None = None,
157
) -> int:
158
    """
159
    Count assistants.
160

161
    Args:
162
        metadata: Metadata to filter by. Exact match filter for each KV pair.
163
        graph_id: ID of a graph to filter by.
164
        headers: Optional custom headers to include with the request.
165
        params: Optional query parameters to include with the request.
166

167
    Returns:
168
        int: Number of assistants that match the query.
169
    """
170
```
171

172
### Graph Schema & Structure
173

174
Retrieve graph definitions, schemas, and subgraph structures associated with assistants.
175

176
```python { .api }
177
from typing import Any
178
from langgraph_sdk.schema import Subgraphs, QueryParamTypes
179

180
async def get_graph(
181
    assistant_id: str,
182
    *,
183
    xray: int | bool = False,
184
    headers: Mapping[str, str] | None = None,
185
    params: QueryParamTypes | None = None,
186
) -> dict[str, list[dict[str, Any]]]:
187
    """
188
    Get the graph of an assistant by ID.
189

190
    Args:
191
        assistant_id: The ID of the assistant to get the graph of.
192
        xray: Include graph representation of subgraphs. If an integer value is provided,
193
              only subgraphs with a depth less than or equal to the value will be included.
194
        headers: Optional custom headers to include with the request.
195
        params: Optional query parameters to include with the request.
196

197
    Returns:
198
        Graph: The graph information for the assistant in JSON format.
199
    """
200

201
async def get_schemas(
202
    assistant_id: str,
203
    *,
204
    headers: Mapping[str, str] | None = None,
205
    params: QueryParamTypes | None = None,
206
) -> dict[str, Any]:
207
    """
208
    Get the schemas of an assistant by ID.
209

210
    Args:
211
        assistant_id: The ID of the assistant to get the schema of.
212
        headers: Optional custom headers to include with the request.
213
        params: Optional query parameters to include with the request.
214

215
    Returns:
216
        Graph: The graph schema for the assistant in JSON format.
217
    """
218

219
async def get_subgraphs(
220
    assistant_id: str,
221
    namespace: str | None = None,
222
    recurse: bool = False,
223
    *,
224
    headers: Mapping[str, str] | None = None,
225
    params: QueryParamTypes | None = None,
226
) -> Subgraphs:
227
    """
228
    Get the subgraphs of an assistant by ID.
229

230
    Args:
231
        assistant_id: The ID of the assistant to get the subgraphs of.
232
        namespace: Optional namespace to filter by.
233
        recurse: Whether to recursively get subgraphs.
234
        headers: Optional custom headers to include with the request.
235
        params: Optional query parameters to include with the request.
236

237
    Returns:
238
        Subgraphs: A mapping of subgraph names to their definitions.
239
    """
240
```
241

242
### Version Management
243

244
Manage assistant versions and control which version is active for execution.
245

246
```python { .api }
247
from langgraph_sdk.schema import AssistantVersion, Json, QueryParamTypes
248

249
async def get_versions(
250
    assistant_id: str,
251
    metadata: Json = None,
252
    limit: int = 10,
253
    offset: int = 0,
254
    *,
255
    headers: Mapping[str, str] | None = None,
256
    params: QueryParamTypes | None = None,
257
) -> list[AssistantVersion]:
258
    """
259
    List all versions of an assistant.
260

261
    Args:
262
        assistant_id: The assistant ID to get versions for.
263
        metadata: Metadata to filter versions by. Exact match filter for each KV pair.
264
        limit: The maximum number of versions to return.
265
        offset: The number of versions to skip.
266
        headers: Optional custom headers to include with the request.
267
        params: Optional query parameters to include with the request.
268

269
    Returns:
270
        list[AssistantVersion]: A list of assistant versions.
271
    """
272

273
async def set_latest(
274
    assistant_id: str,
275
    version: int,
276
    *,
277
    headers: Mapping[str, str] | None = None,
278
    params: QueryParamTypes | None = None,
279
) -> AssistantVersion:
280
    """
281
    Set the latest version of an assistant.
282

283
    Args:
284
        assistant_id: The assistant ID to set the version for.
285
        version: The version to set as the latest.
286
        headers: Optional custom headers to include with the request.
287
        params: Optional query parameters to include with the request.
288

289
    Returns:
290
        AssistantVersion: The updated assistant version.
291
    """
292
```
293

294
## Types
295

296
```python { .api }
297
class Assistant(TypedDict):
298
    """Assistant definition and configuration."""
299
    assistant_id: str
300
    graph_id: str
301
    config: Config
302
    created_at: str
303
    updated_at: str
304
    metadata: dict
305
    version: int
306

307
class AssistantVersion(TypedDict):
308
    """Versioned assistant information."""
309
    assistant_id: str
310
    version: int
311
    config: Config
312
    created_at: str
313
    metadata: dict
314

315
class GraphSchema(TypedDict):
316
    """Graph structure definition."""
317
    graph_id: str
318
    input_schema: dict
319
    output_schema: dict
320
    state_schema: dict
321
    config_schema: dict
322

323
AssistantSelectField = Literal[
324
    "assistant_id", "graph_id", "config", "created_at",
325
    "updated_at", "metadata", "version"
326
]
327

328
AssistantSortBy = Literal["created_at", "updated_at", "assistant_id"]
329

330
IfNotExists = Literal["create", "reject"]
331

332
Subgraphs = dict[str, GraphSchema]
333
```
334

335
## Usage Examples
336

337
### Creating and Managing Assistants
338

339
```python
340
# Create an assistant from a registered graph
341
assistant = await client.assistants.create(
342
    graph_id="my-chatbot-graph",
343
    config={"max_turns": 10, "temperature": 0.7},
344
    metadata={"environment": "production", "owner": "team-ai"}
345
)
346

347
# Get assistant details
348
assistant = await client.assistants.get("assistant-123")
349

350
# Update assistant configuration
351
updated = await client.assistants.update(
352
    "assistant-123",
353
    config={"max_turns": 20},
354
    metadata={"last_updated_by": "admin"}
355
)
356
```
357

358
### Searching and Discovery
359

360
```python
361
# Search assistants by metadata
362
production_assistants = await client.assistants.search(
363
    metadata={"environment": "production"},
364
    limit=50
365
)
366

367
# Get assistants for a specific graph
368
graph_assistants = await client.assistants.search(
369
    graph_id="my-graph",
370
    sort_by="updated_at",
371
    order_by="desc"
372
)
373

374
# Count total assistants
375
total = await client.assistants.count()
376
```
377

378
### Graph Inspection
379

380
```python
381
# Get graph structure
382
graph = await client.assistants.get_graph("assistant-123")
383
print(f"Graph has {len(graph['nodes'])} nodes")
384

385
# Get input/output schemas
386
schemas = await client.assistants.get_schemas("assistant-123")
387
input_schema = schemas["input_schema"]
388

389
# Get subgraphs
390
subgraphs = await client.assistants.get_subgraphs("assistant-123")
391
```
392

393
### Version Control
394

395
```python
396
# Get all versions of an assistant
397
versions = await client.assistants.get_versions("assistant-123")
398

399
# Set specific version as active
400
await client.assistants.set_latest("assistant-123", version=5)
401
```