pypi-langgraph-sdk

1
# Assistant Management
2

3
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.
4

5
## Capabilities
6

7
### Assistant CRUD Operations
8

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

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

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

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

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

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

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

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

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

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

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

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

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

113
### Assistant Discovery & Search
114

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

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

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

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

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

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

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

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

173
### Graph Schema & Structure
174

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

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

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

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

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

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

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

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

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

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

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

243
### Version Management
244

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

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

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

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

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

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

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

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

295
## Types
296

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

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

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

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

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

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

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

336
## Usage Examples
337

338
### Creating and Managing Assistants
339

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

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

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

359
### Searching and Discovery
360

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

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

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

379
### Graph Inspection
380

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

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

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

394
### Version Control
395

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

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