0
# Assistants API
1

2
Build AI assistants with advanced capabilities including code interpretation, file search, and function calling. Assistants maintain conversation state and can access tools to help users accomplish tasks.
3

4
## Capabilities
5

6
### Create Assistant
7

8
Create an AI assistant with specific instructions and tools.
9

10
```python { .api }
11
def create(
12
    self,
13
    *,
14
    model: str,
15
    description: str | Omit = omit,
16
    instructions: str | Omit = omit,
17
    metadata: dict[str, str] | Omit = omit,
18
    name: str | Omit = omit,
19
    reasoning_effort: str | Omit = omit,
20
    response_format: dict | Omit = omit,
21
    temperature: float | Omit = omit,
22
    tool_resources: dict | Omit = omit,
23
    tools: list[dict] | Omit = omit,
24
    top_p: float | Omit = omit,
25
    extra_headers: dict[str, str] | None = None,
26
    extra_query: dict[str, object] | None = None,
27
    extra_body: dict[str, object] | None = None,
28
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
29
) -> Assistant:
30
    """
31
    Create an AI assistant.
32

33
    Args:
34
        model: Model ID to use (e.g., "gpt-4", "gpt-3.5-turbo").
35

36
        description: Description of the assistant (max 512 chars).
37

38
        instructions: System instructions that guide assistant behavior (max 256k chars).
39

40
        metadata: Key-value pairs for storing additional info (max 16).
41
            Keys max 64 chars, values max 512 chars.
42

43
        name: Name of the assistant (max 256 chars).
44

45
        reasoning_effort: Constrains effort on reasoning for reasoning models.
46
            Currently supported values are "none", "minimal", "low", "medium", and "high".
47
            Reducing reasoning effort can result in faster responses and fewer tokens used.
48
            - gpt-5.1 defaults to "none" (no reasoning). Supports: none, low, medium, high.
49
            - Models before gpt-5.1 default to "medium" and do not support "none".
50
            - gpt-5-pro defaults to (and only supports) "high" reasoning effort.
51

52
        response_format: Output format specification.
53
            - {"type": "text"}: Plain text (default)
54
            - {"type": "json_object"}: Valid JSON
55
            - {"type": "json_schema", "json_schema": {...}}: Structured output
56

57
        temperature: Sampling temperature between 0 and 2. Default 1.
58

59
        tool_resources: Resources for tools. Options:
60
            - {"code_interpreter": {"file_ids": [...]}}
61
            - {"file_search": {"vector_store_ids": [...]}}
62

63
        tools: List of enabled tools (maximum of 128 tools per assistant). Options:
64
            - {"type": "code_interpreter"}: Python code execution
65
            - {"type": "file_search"}: Search uploaded files
66
            - {"type": "function", "function": {...}}: Custom functions
67

68
        top_p: Nucleus sampling parameter between 0 and 1. Default 1.
69

70
        extra_headers: Additional HTTP headers.
71
        extra_query: Additional query parameters.
72
        extra_body: Additional JSON fields.
73
        timeout: Request timeout in seconds.
74

75
    Returns:
76
        Assistant: Created assistant.
77

78
    Raises:
79
        BadRequestError: Invalid parameters
80
    """
81
```
82

83
Usage examples:
84

85
```python
86
from openai import OpenAI
87

88
client = OpenAI()
89

90
# Basic assistant
91
assistant = client.beta.assistants.create(
92
    name="Math Tutor",
93
    instructions="You are a helpful math tutor. Explain concepts clearly.",
94
    model="gpt-4"
95
)
96

97
print(f"Assistant ID: {assistant.id}")
98

99
# With code interpreter
100
assistant = client.beta.assistants.create(
101
    name="Data Analyst",
102
    instructions="Analyze data and create visualizations.",
103
    model="gpt-4",
104
    tools=[{"type": "code_interpreter"}]
105
)
106

107
# With file search
108
assistant = client.beta.assistants.create(
109
    name="Documentation Helper",
110
    instructions="Help users find information in documentation.",
111
    model="gpt-4",
112
    tools=[{"type": "file_search"}],
113
    tool_resources={
114
        "file_search": {
115
            "vector_store_ids": ["vs_abc123"]
116
        }
117
    }
118
)
119

120
# With function calling
121
tools = [
122
    {
123
        "type": "function",
124
        "function": {
125
            "name": "get_weather",
126
            "description": "Get current weather",
127
            "parameters": {
128
                "type": "object",
129
                "properties": {
130
                    "location": {"type": "string"}
131
                },
132
                "required": ["location"]
133
            }
134
        }
135
    }
136
]
137

138
assistant = client.beta.assistants.create(
139
    name="Weather Assistant",
140
    instructions="Help users check weather.",
141
    model="gpt-4",
142
    tools=tools
143
)
144

145
# With structured output
146
assistant = client.beta.assistants.create(
147
    name="Structured Assistant",
148
    instructions="Generate structured responses.",
149
    model="gpt-4",
150
    response_format={
151
        "type": "json_schema",
152
        "json_schema": {
153
            "name": "response",
154
            "strict": True,
155
            "schema": {
156
                "type": "object",
157
                "properties": {
158
                    "answer": {"type": "string"}
159
                },
160
                "required": ["answer"],
161
                "additionalProperties": False
162
            }
163
        }
164
    }
165
)
166

167
# With metadata
168
assistant = client.beta.assistants.create(
169
    name="Customer Support",
170
    instructions="Assist customers with inquiries.",
171
    model="gpt-4",
172
    metadata={
173
        "department": "support",
174
        "version": "1.0"
175
    }
176
)
177

178
# With reasoning effort (for reasoning models)
179
assistant = client.beta.assistants.create(
180
    name="Reasoning Assistant",
181
    instructions="Solve complex problems with reasoning.",
182
    model="gpt-5.1",
183
    reasoning_effort="high"
184
)
185
```
186

187
### Retrieve Assistant
188

189
Get assistant details.
190

191
```python { .api }
192
def retrieve(
193
    self,
194
    assistant_id: str,
195
    *,
196
    extra_headers: dict[str, str] | None = None,
197
    extra_query: dict[str, object] | None = None,
198
    extra_body: dict[str, object] | None = None,
199
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
200
) -> Assistant:
201
    """
202
    Retrieve assistant details.
203

204
    Args:
205
        assistant_id: The ID of the assistant.
206
        extra_headers: Additional HTTP headers.
207
        extra_query: Additional query parameters.
208
        extra_body: Additional JSON fields.
209
        timeout: Request timeout in seconds.
210

211
    Returns:
212
        Assistant: Assistant details.
213

214
    Raises:
215
        NotFoundError: Assistant not found
216
    """
217
```
218

219
Usage example:
220

221
```python
222
assistant = client.beta.assistants.retrieve("asst_abc123")
223

224
print(f"Name: {assistant.name}")
225
print(f"Model: {assistant.model}")
226
print(f"Tools: {assistant.tools}")
227
```
228

229
### Update Assistant
230

231
Modify assistant properties.
232

233
```python { .api }
234
def update(
235
    self,
236
    assistant_id: str,
237
    *,
238
    description: str | Omit = omit,
239
    instructions: str | Omit = omit,
240
    metadata: dict[str, str] | Omit = omit,
241
    model: str | Omit = omit,
242
    name: str | Omit = omit,
243
    reasoning_effort: str | Omit = omit,
244
    response_format: dict | Omit = omit,
245
    temperature: float | Omit = omit,
246
    tool_resources: dict | Omit = omit,
247
    tools: list[dict] | Omit = omit,
248
    top_p: float | Omit = omit,
249
    extra_headers: dict[str, str] | None = None,
250
    extra_query: dict[str, object] | None = None,
251
    extra_body: dict[str, object] | None = None,
252
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
253
) -> Assistant:
254
    """
255
    Update assistant properties.
256

257
    Args: Same as create method, but all optional.
258

259
    Returns:
260
        Assistant: Updated assistant.
261
    """
262
```
263

264
Usage example:
265

266
```python
267
# Update instructions
268
assistant = client.beta.assistants.update(
269
    "asst_abc123",
270
    instructions="Updated instructions."
271
)
272

273
# Add tools
274
assistant = client.beta.assistants.update(
275
    "asst_abc123",
276
    tools=[
277
        {"type": "code_interpreter"},
278
        {"type": "file_search"}
279
    ]
280
)
281
```
282

283
### List Assistants
284

285
List all assistants with pagination.
286

287
```python { .api }
288
def list(
289
    self,
290
    *,
291
    after: str | Omit = omit,
292
    before: str | Omit = omit,
293
    limit: int | Omit = omit,
294
    order: Literal["asc", "desc"] | Omit = omit,
295
    extra_headers: dict[str, str] | None = None,
296
    extra_query: dict[str, object] | None = None,
297
    extra_body: dict[str, object] | None = None,
298
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
299
) -> SyncCursorPage[Assistant]:
300
    """
301
    List assistants with pagination.
302

303
    Args:
304
        after: Cursor for next page.
305
        before: Cursor for previous page.
306
        limit: Number to retrieve (max 100). Default 20.
307
        order: Sort order. "asc" or "desc". Default "desc".
308
        extra_headers: Additional HTTP headers.
309
        extra_query: Additional query parameters.
310
        extra_body: Additional JSON fields.
311
        timeout: Request timeout in seconds.
312

313
    Returns:
314
        SyncCursorPage[Assistant]: Paginated list of assistants.
315
    """
316
```
317

318
Usage example:
319

320
```python
321
# List all assistants
322
assistants = client.beta.assistants.list()
323

324
for assistant in assistants:
325
    print(f"{assistant.name} ({assistant.id})")
326

327
# Pagination
328
page1 = client.beta.assistants.list(limit=10)
329
page2 = client.beta.assistants.list(limit=10, after=page1.data[-1].id)
330
```
331

332
### Delete Assistant
333

334
Delete an assistant.
335

336
```python { .api }
337
def delete(
338
    self,
339
    assistant_id: str,
340
    *,
341
    extra_headers: dict[str, str] | None = None,
342
    extra_query: dict[str, object] | None = None,
343
    extra_body: dict[str, object] | None = None,
344
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
345
) -> AssistantDeleted:
346
    """
347
    Delete an assistant.
348

349
    Args:
350
        assistant_id: The ID of the assistant to delete.
351
        extra_headers: Additional HTTP headers.
352
        extra_query: Additional query parameters.
353
        extra_body: Additional JSON fields.
354
        timeout: Request timeout in seconds.
355

356
    Returns:
357
        AssistantDeleted: Deletion confirmation.
358

359
    Raises:
360
        NotFoundError: Assistant not found
361
    """
362
```
363

364
Usage example:
365

366
```python
367
result = client.beta.assistants.delete("asst_abc123")
368

369
print(f"Deleted: {result.deleted}")
370
```
371

372
## Types
373

374
```python { .api }
375
from typing import Literal
376
from pydantic import BaseModel
377

378
class Assistant(BaseModel):
379
    """AI Assistant."""
380
    id: str
381
    created_at: int
382
    description: str | None
383
    instructions: str | None
384
    metadata: dict[str, str] | None
385
    model: str
386
    name: str | None
387
    object: Literal["assistant"]
388
    tools: list[dict]
389
    response_format: dict | None
390
    temperature: float | None
391
    tool_resources: dict | None
392
    top_p: float | None
393

394
class AssistantDeleted(BaseModel):
395
    """Deletion confirmation."""
396
    id: str
397
    deleted: bool
398
    object: Literal["assistant.deleted"]
399

400
# Tool types
401
class CodeInterpreterTool(TypedDict):
402
    type: Literal["code_interpreter"]
403

404
class FileSearchTool(TypedDict):
405
    type: Literal["file_search"]
406

407
class FunctionTool(TypedDict):
408
    type: Literal["function"]
409
    function: FunctionDefinition
410

411
class FunctionDefinition(TypedDict):
412
    name: str
413
    description: NotRequired[str]
414
    parameters: dict  # JSON Schema
415
    strict: NotRequired[bool]
416

417
# Tool resources
418
class ToolResources(TypedDict, total=False):
419
    code_interpreter: CodeInterpreterResources
420
    file_search: FileSearchResources
421

422
class CodeInterpreterResources(TypedDict, total=False):
423
    file_ids: list[str]
424

425
class FileSearchResources(TypedDict, total=False):
426
    vector_store_ids: list[str]
427
```
428

429
## Best Practices
430

431
```python
432
from openai import OpenAI
433

434
client = OpenAI()
435

436
# 1. Create specialized assistants
437
support_assistant = client.beta.assistants.create(
438
    name="Customer Support",
439
    instructions="Friendly and helpful support agent.",
440
    model="gpt-4",
441
    tools=[{"type": "file_search"}]
442
)
443

444
code_assistant = client.beta.assistants.create(
445
    name="Code Helper",
446
    instructions="Help with coding questions.",
447
    model="gpt-4",
448
    tools=[{"type": "code_interpreter"}]
449
)
450

451
# 2. Organize with metadata
452
assistant = client.beta.assistants.create(
453
    name="Sales Bot",
454
    model="gpt-4",
455
    metadata={
456
        "team": "sales",
457
        "region": "us-west",
458
        "version": "2.0"
459
    }
460
)
461

462
# 3. Update as needed
463
assistant = client.beta.assistants.update(
464
    assistant.id,
465
    instructions="Updated instructions based on feedback."
466
)
467

468
# 4. Clean up unused assistants
469
assistants = client.beta.assistants.list()
470
for assistant in assistants:
471
    if should_delete(assistant):
472
        client.beta.assistants.delete(assistant.id)
473
```
474

475
## Complete Example
476

477
```python
478
from openai import OpenAI
479

480
client = OpenAI()
481

482
# 1. Create assistant
483
assistant = client.beta.assistants.create(
484
    name="Math Tutor",
485
    instructions="You are a helpful math tutor.",
486
    model="gpt-4",
487
    tools=[{"type": "code_interpreter"}]
488
)
489

490
# 2. Create thread
491
thread = client.beta.threads.create()
492

493
# 3. Add message
494
message = client.beta.threads.messages.create(
495
    thread_id=thread.id,
496
    role="user",
497
    content="Can you help me solve x^2 + 5x + 6 = 0?"
498
)
499

500
# 4. Run assistant
501
run = client.beta.threads.runs.create(
502
    thread_id=thread.id,
503
    assistant_id=assistant.id
504
)
505

506
# 5. Wait for completion
507
import time
508

509
while run.status not in ["completed", "failed"]:
510
    time.sleep(1)
511
    run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
512

513
# 6. Get response
514
messages = client.beta.threads.messages.list(thread_id=thread.id)
515

516
for message in messages.data:
517
    if message.role == "assistant":
518
        print(message.content[0].text.value)
519
```
520

521
## Async Usage
522

523
```python
524
import asyncio
525
from openai import AsyncOpenAI
526

527
async def create_assistant():
528
    client = AsyncOpenAI()
529

530
    assistant = await client.beta.assistants.create(
531
        name="Async Assistant",
532
        model="gpt-4",
533
        instructions="I help async."
534
    )
535

536
    return assistant.id
537

538
assistant_id = asyncio.run(create_assistant())
539
```
540