0
# Assistants API
1

2
The OpenAI Assistants API (v2) enables building AI assistants with persistent threads, tool use (code interpreter, file search, function calling), and streaming support. This beta feature provides a stateful approach to building AI applications.
3

4
**Note:** The Assistants API has been marked as deprecated in favor of the Responses API in recent SDK versions, but remains fully functional.
5

6
## Package Information
7

8
- **Package Name**: openai
9
- **Version**: 6.9.1+
10
- **Language**: TypeScript
11
- **API Access**: `client.beta.assistants`, `client.beta.threads`
12

13
## Core Imports
14

15
```typescript
16
import OpenAI from "openai";
17

18
const client = new OpenAI({
19
  apiKey: process.env.OPENAI_API_KEY,
20
});
21

22
// Access Assistants API
23
const assistant = await client.beta.assistants.create({ model: "gpt-4o" });
24
const thread = await client.beta.threads.create();
25
const run = await client.beta.threads.runs.create(thread.id, {
26
  assistant_id: assistant.id,
27
});
28
```
29

30
## Architecture
31

32
The Assistants API is organized hierarchically:
33

34
- **Assistants** (`client.beta.assistants`) - AI assistants with instructions and tools
35
- **Threads** (`client.beta.threads`) - Conversation threads containing messages
36
- **Messages** (`client.beta.threads.messages`) - User and assistant messages in threads
37
- **Runs** (`client.beta.threads.runs`) - Execution of an assistant on a thread
38
- **Run Steps** (`client.beta.threads.runs.steps`) - Individual steps within a run
39

40
Key capabilities:
41
- **Stateful Conversations**: Threads maintain conversation history automatically
42
- **Tool Use**: Code interpreter, file search, and function calling
43
- **Streaming**: Real-time streaming of responses with granular events
44
- **Polling Helpers**: Automatic polling for long-running operations
45
- **File Management**: Attach files for code execution and search
46

47
## API Resources
48

49
### Assistants (`client.beta.assistants`)
50

51
Create and manage AI assistants with custom instructions, tools, and configuration.
52

53
#### Methods
54

55
##### create
56

57
```typescript { .api }
58
/**
59
 * Create an assistant with a model and instructions
60
 * @param body - Assistant configuration
61
 * @returns Promise<Assistant>
62
 */
63
create(
64
  body: AssistantCreateParams,
65
  options?: RequestOptions
66
): Promise<Assistant>;
67
```
68

69
**Usage:**
70

71
```typescript
72
const assistant = await client.beta.assistants.create({
73
  model: "gpt-4o",
74
  name: "Math Tutor",
75
  instructions: "You are a helpful math tutor. Guide students step by step.",
76
  tools: [
77
    { type: "code_interpreter" },
78
    { type: "file_search" }
79
  ],
80
  tool_resources: {
81
    code_interpreter: {
82
      file_ids: ["file-123"]
83
    },
84
    file_search: {
85
      vector_store_ids: ["vs-456"]
86
    }
87
  },
88
  temperature: 0.7,
89
  metadata: { department: "education" }
90
});
91
```
92

93
##### retrieve
94

95
```typescript { .api }
96
/**
97
 * Retrieves an assistant by ID
98
 * @param assistantID - The assistant ID
99
 * @returns Promise<Assistant>
100
 */
101
retrieve(
102
  assistantID: string,
103
  options?: RequestOptions
104
): Promise<Assistant>;
105
```
106

107
##### update
108

109
```typescript { .api }
110
/**
111
 * Modifies an assistant
112
 * @param assistantID - The assistant ID
113
 * @param body - Fields to update
114
 * @returns Promise<Assistant>
115
 */
116
update(
117
  assistantID: string,
118
  body: AssistantUpdateParams,
119
  options?: RequestOptions
120
): Promise<Assistant>;
121
```
122

123
**Usage:**
124

125
```typescript
126
const updated = await client.beta.assistants.update(assistant.id, {
127
  instructions: "Updated instructions",
128
  tools: [{ type: "code_interpreter" }, { type: "function", function: myFunc }],
129
  metadata: { version: "2.0" }
130
});
131
```
132

133
##### list
134

135
```typescript { .api }
136
/**
137
 * Returns a list of assistants with pagination support
138
 * @param query - Pagination parameters
139
 * @returns PagePromise<AssistantsPage, Assistant>
140
 */
141
list(
142
  query?: AssistantListParams,
143
  options?: RequestOptions
144
): PagePromise<AssistantsPage, Assistant>;
145
```
146

147
**Usage:**
148

149
```typescript
150
// Auto-pagination with async iteration
151
for await (const assistant of client.beta.assistants.list({ limit: 20 })) {
152
  console.log(assistant.name);
153
}
154

155
// Manual pagination
156
const page = await client.beta.assistants.list({ limit: 10, order: "desc" });
157
```
158

159
##### delete
160

161
```typescript { .api }
162
/**
163
 * Delete an assistant
164
 * @param assistantID - The assistant ID
165
 * @returns Promise<AssistantDeleted>
166
 */
167
delete(
168
  assistantID: string,
169
  options?: RequestOptions
170
): Promise<AssistantDeleted>;
171
```
172

173
#### Types
174

175
##### Assistant
176

177
```typescript { .api }
178
/**
179
 * Represents an assistant that can call the model and use tools
180
 */
181
interface Assistant {
182
  /** The identifier, which can be referenced in API endpoints */
183
  id: string;
184

185
  /** The Unix timestamp (in seconds) for when the assistant was created */
186
  created_at: number;
187

188
  /** The description of the assistant (max 512 characters) */
189
  description: string | null;
190

191
  /** System instructions for the assistant (max 256,000 characters) */
192
  instructions: string | null;
193

194
  /** Key-value metadata pairs (max 16 pairs) */
195
  metadata: Metadata | null;
196

197
  /** ID of the model to use */
198
  model: string;
199

200
  /** The name of the assistant (max 256 characters) */
201
  name: string | null;
202

203
  /** Always 'assistant' */
204
  object: "assistant";
205

206
  /** List of tools enabled on the assistant (max 128 tools) */
207
  tools: Array<AssistantTool>;
208

209
  /** Response format specification (json_schema, json_object, or auto) */
210
  response_format?: AssistantResponseFormatOption | null;
211

212
  /** Sampling temperature (0-2) */
213
  temperature?: number | null;
214

215
  /** Tool-specific resources (files for code_interpreter, vector stores for file_search) */
216
  tool_resources?: Assistant.ToolResources | null;
217

218
  /** Nucleus sampling parameter (0-1) */
219
  top_p?: number | null;
220
}
221
```
222

223
##### AssistantTool
224

225
```typescript { .api }
226
/**
227
 * Tool definitions for assistants
228
 */
229
type AssistantTool = CodeInterpreterTool | FileSearchTool | FunctionTool;
230

231
interface CodeInterpreterTool {
232
  /** Always 'code_interpreter' */
233
  type: "code_interpreter";
234
}
235

236
interface FileSearchTool {
237
  /** Always 'file_search' */
238
  type: "file_search";
239

240
  /** Configuration for file search */
241
  file_search?: {
242
    /** Max results to return (1-50, default 20 for gpt-4, 5 for gpt-3.5) */
243
    max_num_results?: number;
244

245
    /** Ranking configuration */
246
    ranking_options?: {
247
      /** Score threshold (0-1) */
248
      score_threshold: number;
249
      /** Ranker type */
250
      ranker?: "auto" | "default_2024_08_21";
251
    };
252
  };
253
}
254

255
interface FunctionTool {
256
  /** Function definition */
257
  function: FunctionDefinition;
258

259
  /** Always 'function' */
260
  type: "function";
261
}
262
```
263

264
##### AssistantCreateParams
265

266
```typescript { .api }
267
/**
268
 * Parameters for creating an assistant
269
 */
270
interface AssistantCreateParams {
271
  /** Model ID to use */
272
  model: string | ChatModel;
273

274
  /** Description (max 512 chars) */
275
  description?: string | null;
276

277
  /** System instructions (max 256,000 chars) */
278
  instructions?: string | null;
279

280
  /** Metadata key-value pairs */
281
  metadata?: Metadata | null;
282

283
  /** Name (max 256 chars) */
284
  name?: string | null;
285

286
  /** Reasoning effort (none, minimal, low, medium, high) */
287
  reasoning_effort?: ReasoningEffort | null;
288

289
  /** Response format configuration */
290
  response_format?: AssistantResponseFormatOption | null;
291

292
  /** Temperature (0-2) */
293
  temperature?: number | null;
294

295
  /** Tool resources (files, vector stores) */
296
  tool_resources?: AssistantCreateParams.ToolResources | null;
297

298
  /** Tools to enable */
299
  tools?: Array<AssistantTool>;
300

301
  /** Top-p sampling (0-1) */
302
  top_p?: number | null;
303
}
304
```
305

306
##### AssistantDeleted
307

308
```typescript { .api }
309
/**
310
 * Confirmation of assistant deletion
311
 */
312
interface AssistantDeleted {
313
  id: string;
314
  deleted: boolean;
315
  object: "assistant.deleted";
316
}
317
```
318

319
---
320

321
### Threads (`client.beta.threads`)
322

323
Manage conversation threads that contain messages and maintain state.
324

325
#### Methods
326

327
##### create
328

329
```typescript { .api }
330
/**
331
 * Create a thread with optional initial messages
332
 * @param body - Thread configuration
333
 * @returns Promise<Thread>
334
 */
335
create(
336
  body?: ThreadCreateParams,
337
  options?: RequestOptions
338
): Promise<Thread>;
339
```
340

341
**Usage:**
342

343
```typescript
344
// Empty thread
345
const thread = await client.beta.threads.create();
346

347
// Thread with initial messages
348
const thread = await client.beta.threads.create({
349
  messages: [
350
    {
351
      role: "user",
352
      content: "Hello! I need help with calculus.",
353
      attachments: [
354
        {
355
          file_id: "file-123",
356
          tools: [{ type: "file_search" }]
357
        }
358
      ]
359
    }
360
  ],
361
  tool_resources: {
362
    code_interpreter: { file_ids: ["file-456"] }
363
  },
364
  metadata: { session_id: "abc123" }
365
});
366
```
367

368
##### retrieve
369

370
```typescript { .api }
371
/**
372
 * Retrieves a thread
373
 * @param threadID - The thread ID
374
 * @returns Promise<Thread>
375
 */
376
retrieve(
377
  threadID: string,
378
  options?: RequestOptions
379
): Promise<Thread>;
380
```
381

382
##### update
383

384
```typescript { .api }
385
/**
386
 * Modifies a thread's metadata or tool resources
387
 * @param threadID - The thread ID
388
 * @param body - Fields to update
389
 * @returns Promise<Thread>
390
 */
391
update(
392
  threadID: string,
393
  body: ThreadUpdateParams,
394
  options?: RequestOptions
395
): Promise<Thread>;
396
```
397

398
##### delete
399

400
```typescript { .api }
401
/**
402
 * Delete a thread
403
 * @param threadID - The thread ID
404
 * @returns Promise<ThreadDeleted>
405
 */
406
delete(
407
  threadID: string,
408
  options?: RequestOptions
409
): Promise<ThreadDeleted>;
410
```
411

412
##### createAndRun
413

414
```typescript { .api }
415
/**
416
 * Create a thread and immediately start a run (supports streaming)
417
 * @param body - Thread and run configuration
418
 * @returns Promise<Run> | Promise<Stream<AssistantStreamEvent>>
419
 */
420
createAndRun(
421
  body: ThreadCreateAndRunParamsNonStreaming,
422
  options?: RequestOptions
423
): Promise<Run>;
424

425
createAndRun(
426
  body: ThreadCreateAndRunParamsStreaming,
427
  options?: RequestOptions
428
): Promise<Stream<AssistantStreamEvent>>;
429
```
430

431
**Usage:**
432

433
```typescript
434
// Non-streaming
435
const run = await client.beta.threads.createAndRun({
436
  assistant_id: assistant.id,
437
  thread: {
438
    messages: [{ role: "user", content: "Explain quantum physics" }]
439
  }
440
});
441

442
// Streaming
443
const stream = await client.beta.threads.createAndRun({
444
  assistant_id: assistant.id,
445
  thread: {
446
    messages: [{ role: "user", content: "Write a story" }]
447
  },
448
  stream: true
449
});
450

451
for await (const event of stream) {
452
  if (event.event === "thread.message.delta") {
453
    process.stdout.write(event.data.delta.content?.[0]?.text?.value || "");
454
  }
455
}
456
```
457

458
##### createAndRunPoll
459

460
```typescript { .api }
461
/**
462
 * Helper: Create thread, run, and poll until completion
463
 * @param body - Thread and run configuration
464
 * @param options - Options including pollIntervalMs
465
 * @returns Promise<Run>
466
 */
467
createAndRunPoll(
468
  body: ThreadCreateAndRunParamsNonStreaming,
469
  options?: RequestOptions & { pollIntervalMs?: number }
470
): Promise<Run>;
471
```
472

473
**Usage:**
474

475
```typescript
476
const run = await client.beta.threads.createAndRunPoll({
477
  assistant_id: assistant.id,
478
  thread: {
479
    messages: [{ role: "user", content: "Calculate 234 * 567" }]
480
  }
481
}, { pollIntervalMs: 1000 });
482

483
// Run is now in terminal state (completed, failed, etc.)
484
console.log(run.status); // "completed"
485
```
486

487
##### createAndRunStream
488

489
```typescript { .api }
490
/**
491
 * Helper: Create thread and stream the run with typed AssistantStream
492
 * @param body - Thread and run configuration
493
 * @returns AssistantStream
494
 */
495
createAndRunStream(
496
  body: ThreadCreateAndRunParamsBaseStream,
497
  options?: RequestOptions
498
): AssistantStream;
499
```
500

501
**Usage:**
502

503
```typescript
504
const stream = client.beta.threads.createAndRunStream({
505
  assistant_id: assistant.id,
506
  thread: {
507
    messages: [{ role: "user", content: "Help me debug this code" }]
508
  }
509
});
510

511
stream
512
  .on("textCreated", () => process.stdout.write("\nassistant > "))
513
  .on("textDelta", (delta) => process.stdout.write(delta.value || ""))
514
  .on("textDone", () => console.log("\n"))
515
  .on("toolCallCreated", (toolCall) => console.log(`Tool: ${toolCall.type}`))
516
  .on("toolCallDelta", (delta, snapshot) => {
517
    if (delta.type === "code_interpreter" && delta.code_interpreter?.input) {
518
      process.stdout.write(delta.code_interpreter.input);
519
    }
520
  });
521

522
const finalRun = await stream.finalRun();
523
```
524

525
#### Types
526

527
##### Thread
528

529
```typescript { .api }
530
/**
531
 * Represents a thread that contains messages
532
 */
533
interface Thread {
534
  /** The identifier */
535
  id: string;
536

537
  /** Creation timestamp (Unix seconds) */
538
  created_at: number;
539

540
  /** Metadata key-value pairs */
541
  metadata: Metadata | null;
542

543
  /** Always 'thread' */
544
  object: "thread";
545

546
  /** Tool resources available in this thread */
547
  tool_resources: Thread.ToolResources | null;
548
}
549

550
namespace Thread {
551
  interface ToolResources {
552
    code_interpreter?: {
553
      /** File IDs for code interpreter (max 20) */
554
      file_ids?: Array<string>;
555
    };
556

557
    file_search?: {
558
      /** Vector store IDs for file search (max 1) */
559
      vector_store_ids?: Array<string>;
560
    };
561
  }
562
}
563
```
564

565
##### ThreadDeleted
566

567
```typescript { .api }
568
/**
569
 * Confirmation of thread deletion
570
 */
571
interface ThreadDeleted {
572
  id: string;
573
  deleted: boolean;
574
  object: "thread.deleted";
575
}
576
```
577

578
##### ThreadCreateParams
579

580
```typescript { .api }
581
/**
582
 * Parameters for creating a thread
583
 */
584
interface ThreadCreateParams {
585
  /** Initial messages for the thread */
586
  messages?: Array<ThreadCreateParams.Message>;
587

588
  /** Metadata key-value pairs */
589
  metadata?: Metadata | null;
590

591
  /** Tool resources */
592
  tool_resources?: ThreadCreateParams.ToolResources | null;
593
}
594

595
namespace ThreadCreateParams {
596
  interface Message {
597
    /** Message text or content parts */
598
    content: string | Array<MessageContentPartParam>;
599

600
    /** Message role */
601
    role: "user" | "assistant";
602

603
    /** File attachments */
604
    attachments?: Array<Attachment> | null;
605

606
    /** Metadata */
607
    metadata?: Metadata | null;
608
  }
609

610
  interface Attachment {
611
    /** File ID */
612
    file_id?: string;
613

614
    /** Tools to use with this file */
615
    tools?: Array<CodeInterpreterTool | FileSearchTool>;
616
  }
617
}
618
```
619

620
---
621

622
### Messages (`client.beta.threads.messages`)
623

624
Create and manage messages within threads.
625

626
#### Methods
627

628
##### create
629

630
```typescript { .api }
631
/**
632
 * Create a message in a thread
633
 * @param threadID - The thread ID
634
 * @param body - Message configuration
635
 * @returns Promise<Message>
636
 */
637
create(
638
  threadID: string,
639
  body: MessageCreateParams,
640
  options?: RequestOptions
641
): Promise<Message>;
642
```
643

644
**Usage:**
645

646
```typescript
647
const message = await client.beta.threads.messages.create(thread.id, {
648
  role: "user",
649
  content: "Analyze this data and create visualizations",
650
  attachments: [
651
    {
652
      file_id: "file-789",
653
      tools: [{ type: "code_interpreter" }]
654
    }
655
  ]
656
});
657

658
// Multi-modal message
659
const message = await client.beta.threads.messages.create(thread.id, {
660
  role: "user",
661
  content: [
662
    { type: "text", text: "What's in this image?" },
663
    {
664
      type: "image_url",
665
      image_url: { url: "https://example.com/image.jpg" }
666
    }
667
  ]
668
});
669
```
670

671
##### retrieve
672

673
```typescript { .api }
674
/**
675
 * Retrieve a message
676
 * @param messageID - The message ID
677
 * @param params - Thread ID parameter
678
 * @returns Promise<Message>
679
 */
680
retrieve(
681
  messageID: string,
682
  params: MessageRetrieveParams,
683
  options?: RequestOptions
684
): Promise<Message>;
685
```
686

687
##### update
688

689
```typescript { .api }
690
/**
691
 * Update a message's metadata
692
 * @param messageID - The message ID
693
 * @param params - Thread ID and metadata
694
 * @returns Promise<Message>
695
 */
696
update(
697
  messageID: string,
698
  params: MessageUpdateParams,
699
  options?: RequestOptions
700
): Promise<Message>;
701
```
702

703
##### list
704

705
```typescript { .api }
706
/**
707
 * List messages in a thread with pagination
708
 * @param threadID - The thread ID
709
 * @param query - Pagination and filter parameters
710
 * @returns PagePromise<MessagesPage, Message>
711
 */
712
list(
713
  threadID: string,
714
  query?: MessageListParams,
715
  options?: RequestOptions
716
): PagePromise<MessagesPage, Message>;
717
```
718

719
**Usage:**
720

721
```typescript
722
// Iterate all messages
723
for await (const message of client.beta.threads.messages.list(thread.id)) {
724
  console.log(`${message.role}: ${message.content[0].text?.value}`);
725
}
726

727
// Filter by run and order
728
const messages = await client.beta.threads.messages.list(thread.id, {
729
  run_id: run.id,
730
  order: "asc",
731
  limit: 100
732
});
733
```
734

735
##### delete
736

737
```typescript { .api }
738
/**
739
 * Delete a message
740
 * @param messageID - The message ID
741
 * @param params - Thread ID parameter
742
 * @returns Promise<MessageDeleted>
743
 */
744
delete(
745
  messageID: string,
746
  params: MessageDeleteParams,
747
  options?: RequestOptions
748
): Promise<MessageDeleted>;
749
```
750

751
#### Types
752

753
##### Message
754

755
```typescript { .api }
756
/**
757
 * Represents a message within a thread
758
 */
759
interface Message {
760
  /** The identifier */
761
  id: string;
762

763
  /** Assistant ID that authored this message (if applicable) */
764
  assistant_id: string | null;
765

766
  /** File attachments */
767
  attachments: Array<Message.Attachment> | null;
768

769
  /** Completion timestamp (Unix seconds) */
770
  completed_at: number | null;
771

772
  /** Message content (text, images, etc.) */
773
  content: Array<MessageContent>;
774

775
  /** Creation timestamp (Unix seconds) */
776
  created_at: number;
777

778
  /** When message was marked incomplete */
779
  incomplete_at: number | null;
780

781
  /** Details about why message is incomplete */
782
  incomplete_details: Message.IncompleteDetails | null;
783

784
  /** Metadata */
785
  metadata: Metadata | null;
786

787
  /** Always 'thread.message' */
788
  object: "thread.message";
789

790
  /** Message role */
791
  role: "user" | "assistant";
792

793
  /** Associated run ID */
794
  run_id: string | null;
795

796
  /** Message status */
797
  status: "in_progress" | "incomplete" | "completed";
798

799
  /** Parent thread ID */
800
  thread_id: string;
801
}
802

803
namespace Message {
804
  interface IncompleteDetails {
805
    /** Reason for incompletion */
806
    reason: "content_filter" | "max_tokens" | "run_cancelled" | "run_expired" | "run_failed";
807
  }
808
}
809
```
810

811
##### MessageContent
812

813
```typescript { .api }
814
/**
815
 * Content types in messages
816
 */
817
type MessageContent =
818
  | ImageFileContentBlock
819
  | ImageURLContentBlock
820
  | TextContentBlock
821
  | RefusalContentBlock;
822

823
interface TextContentBlock {
824
  text: Text;
825
  type: "text";
826
}
827

828
interface Text {
829
  /** Annotations (file citations, file paths) */
830
  annotations: Array<Annotation>;
831

832
  /** The text data */
833
  value: string;
834
}
835

836
interface ImageFileContentBlock {
837
  image_file: ImageFile;
838
  type: "image_file";
839
}
840

841
interface ImageFile {
842
  /** File ID of the image */
843
  file_id: string;
844

845
  /** Detail level (auto, low, high) */
846
  detail?: "auto" | "low" | "high";
847
}
848

849
interface ImageURLContentBlock {
850
  image_url: ImageURL;
851
  type: "image_url";
852
}
853

854
interface ImageURL {
855
  /** External image URL */
856
  url: string;
857

858
  /** Detail level (auto, low, high) */
859
  detail?: "auto" | "low" | "high";
860
}
861

862
interface RefusalContentBlock {
863
  /** Refusal text */
864
  refusal: string;
865

866
  /** Always 'refusal' */
867
  type: "refusal";
868
}
869
```
870

871
##### Annotation
872

873
```typescript { .api }
874
/**
875
 * Annotations within message text
876
 */
877
type Annotation = FileCitationAnnotation | FilePathAnnotation;
878

879
/**
880
 * Citation pointing to a specific quote from a file (file_search tool)
881
 */
882
interface FileCitationAnnotation {
883
  /** End index in text */
884
  end_index: number;
885

886
  /** Citation details */
887
  file_citation: {
888
    /** File ID being cited */
889
    file_id: string;
890
  };
891

892
  /** Start index in text */
893
  start_index: number;
894

895
  /** Text to be replaced */
896
  text: string;
897

898
  /** Always 'file_citation' */
899
  type: "file_citation";
900
}
901

902
/**
903
 * URL for file generated by code_interpreter tool
904
 */
905
interface FilePathAnnotation {
906
  /** End index in text */
907
  end_index: number;
908

909
  /** File path details */
910
  file_path: {
911
    /** Generated file ID */
912
    file_id: string;
913
  };
914

915
  /** Start index in text */
916
  start_index: number;
917

918
  /** Text to be replaced */
919
  text: string;
920

921
  /** Always 'file_path' */
922
  type: "file_path";
923
}
924
```
925

926
##### AnnotationDelta
927

928
```typescript { .api }
929
/**
930
 * Annotation deltas during streaming
931
 */
932
type AnnotationDelta = FileCitationDeltaAnnotation | FilePathDeltaAnnotation;
933

934
/**
935
 * Citation delta during streaming (file_search tool)
936
 */
937
interface FileCitationDeltaAnnotation {
938
  /** The index of the annotation in the text content part */
939
  index: number;
940

941
  /** Always 'file_citation' */
942
  type: "file_citation";
943

944
  /** Citation details */
945
  file_citation?: {
946
    /** The ID of the specific File the citation is from */
947
    file_id?: string;
948

949
    /** The specific quote in the file */
950
    quote?: string;
951
  };
952

953
  /** Start index in text */
954
  start_index?: number;
955

956
  /** End index in text */
957
  end_index?: number;
958

959
  /** The text in the message content that needs to be replaced */
960
  text?: string;
961
}
962

963
/**
964
 * File path delta during streaming (code_interpreter tool)
965
 */
966
interface FilePathDeltaAnnotation {
967
  /** The index of the annotation in the text content part */
968
  index: number;
969

970
  /** Always 'file_path' */
971
  type: "file_path";
972

973
  /** File path details */
974
  file_path?: {
975
    /** Generated file ID */
976
    file_id?: string;
977
  };
978

979
  /** Start index in text */
980
  start_index?: number;
981

982
  /** End index in text */
983
  end_index?: number;
984

985
  /** The text in the message content that needs to be replaced */
986
  text?: string;
987
}
988
```
989

990
##### MessageDelta & MessageDeltaEvent
991

992
```typescript { .api }
993
/**
994
 * Delta containing changed fields during streaming
995
 */
996
interface MessageDelta {
997
  /** Content deltas */
998
  content?: Array<MessageContentDelta>;
999

1000
  /** Role */
1001
  role?: "user" | "assistant";
1002
}
1003

1004
/**
1005
 * Message delta event during streaming
1006
 */
1007
interface MessageDeltaEvent {
1008
  /** Message ID */
1009
  id: string;
1010

1011
  /** The delta */
1012
  delta: MessageDelta;
1013

1014
  /** Always 'thread.message.delta' */
1015
  object: "thread.message.delta";
1016
}
1017

1018
/**
1019
 * Content delta types
1020
 */
1021
type MessageContentDelta =
1022
  | ImageFileDeltaBlock
1023
  | TextDeltaBlock
1024
  | RefusalDeltaBlock
1025
  | ImageURLDeltaBlock;
1026

1027
interface TextDeltaBlock {
1028
  /** Content index */
1029
  index: number;
1030

1031
  /** Always 'text' */
1032
  type: "text";
1033

1034
  /** Text delta */
1035
  text?: TextDelta;
1036
}
1037

1038
interface TextDelta {
1039
  /** Annotation deltas */
1040
  annotations?: Array<AnnotationDelta>;
1041

1042
  /** Text value delta */
1043
  value?: string;
1044
}
1045
```
1046

1047
---
1048

1049
### Runs (`client.beta.threads.runs`)
1050

1051
Execute an assistant on a thread with optional streaming and tool calling.
1052

1053
#### Methods
1054

1055
##### create
1056

1057
```typescript { .api }
1058
/**
1059
 * Create a run on a thread (supports streaming)
1060
 * @param threadID - The thread ID
1061
 * @param params - Run configuration
1062
 * @returns Promise<Run> | Promise<Stream<AssistantStreamEvent>>
1063
 */
1064
create(
1065
  threadID: string,
1066
  params: RunCreateParamsNonStreaming,
1067
  options?: RequestOptions
1068
): Promise<Run>;
1069

1070
create(
1071
  threadID: string,
1072
  params: RunCreateParamsStreaming,
1073
  options?: RequestOptions
1074
): Promise<Stream<AssistantStreamEvent>>;
1075
```
1076

1077
**Usage:**
1078

1079
```typescript
1080
// Basic run
1081
const run = await client.beta.threads.runs.create(thread.id, {
1082
  assistant_id: assistant.id
1083
});
1084

1085
// Run with overrides
1086
const run = await client.beta.threads.runs.create(thread.id, {
1087
  assistant_id: assistant.id,
1088
  instructions: "Additional instructions for this run only",
1089
  additional_messages: [
1090
    { role: "user", content: "Context for this run" }
1091
  ],
1092
  model: "gpt-4o",
1093
  tools: [{ type: "code_interpreter" }],
1094
  temperature: 0.8,
1095
  max_prompt_tokens: 10000,
1096
  max_completion_tokens: 2000,
1097
  parallel_tool_calls: true,
1098
  tool_choice: "auto",
1099
  metadata: { session: "xyz" }
1100
});
1101

1102
// Streaming run
1103
const stream = await client.beta.threads.runs.create(thread.id, {
1104
  assistant_id: assistant.id,
1105
  stream: true
1106
});
1107

1108
for await (const event of stream) {
1109
  console.log(event.event, event.data);
1110
}
1111
```
1112

1113
##### retrieve
1114

1115
```typescript { .api }
1116
/**
1117
 * Retrieve a run
1118
 * @param runID - The run ID
1119
 * @param params - Thread ID parameter
1120
 * @returns Promise<Run>
1121
 */
1122
retrieve(
1123
  runID: string,
1124
  params: RunRetrieveParams,
1125
  options?: RequestOptions
1126
): Promise<Run>;
1127
```
1128

1129
##### update
1130

1131
```typescript { .api }
1132
/**
1133
 * Update a run's metadata
1134
 * @param runID - The run ID
1135
 * @param params - Thread ID and metadata
1136
 * @returns Promise<Run>
1137
 */
1138
update(
1139
  runID: string,
1140
  params: RunUpdateParams,
1141
  options?: RequestOptions
1142
): Promise<Run>;
1143
```
1144

1145
##### list
1146

1147
```typescript { .api }
1148
/**
1149
 * List runs for a thread
1150
 * @param threadID - The thread ID
1151
 * @param query - Pagination parameters
1152
 * @returns PagePromise<RunsPage, Run>
1153
 */
1154
list(
1155
  threadID: string,
1156
  query?: RunListParams,
1157
  options?: RequestOptions
1158
): PagePromise<RunsPage, Run>;
1159
```
1160

1161
##### cancel
1162

1163
```typescript { .api }
1164
/**
1165
 * Cancel an in-progress run
1166
 * @param runID - The run ID
1167
 * @param params - Thread ID parameter
1168
 * @returns Promise<Run>
1169
 */
1170
cancel(
1171
  runID: string,
1172
  params: RunCancelParams,
1173
  options?: RequestOptions
1174
): Promise<Run>;
1175
```
1176

1177
##### submitToolOutputs
1178

1179
```typescript { .api }
1180
/**
1181
 * Submit tool outputs for a run requiring action (supports streaming)
1182
 * @param runID - The run ID
1183
 * @param params - Tool outputs and thread ID
1184
 * @returns Promise<Run> | Promise<Stream<AssistantStreamEvent>>
1185
 */
1186
submitToolOutputs(
1187
  runID: string,
1188
  params: RunSubmitToolOutputsParamsNonStreaming,
1189
  options?: RequestOptions
1190
): Promise<Run>;
1191

1192
submitToolOutputs(
1193
  runID: string,
1194
  params: RunSubmitToolOutputsParamsStreaming,
1195
  options?: RequestOptions
1196
): Promise<Stream<AssistantStreamEvent>>;
1197
```
1198

1199
**Usage:**
1200

1201
```typescript
1202
// Check if action is required
1203
let run = await client.beta.threads.runs.retrieve(run.id, {
1204
  thread_id: thread.id
1205
});
1206

1207
if (run.status === "requires_action" &&
1208
    run.required_action?.type === "submit_tool_outputs") {
1209

1210
  const toolCalls = run.required_action.submit_tool_outputs.tool_calls;
1211
  const toolOutputs = [];
1212

1213
  for (const toolCall of toolCalls) {
1214
    if (toolCall.type === "function") {
1215
      const args = JSON.parse(toolCall.function.arguments);
1216
      const result = await myFunction(args);
1217

1218
      toolOutputs.push({
1219
        tool_call_id: toolCall.id,
1220
        output: JSON.stringify(result)
1221
      });
1222
    }
1223
  }
1224

1225
  run = await client.beta.threads.runs.submitToolOutputs(run.id, {
1226
    thread_id: thread.id,
1227
    tool_outputs: toolOutputs
1228
  });
1229
}
1230
```
1231

1232
##### createAndPoll
1233

1234
```typescript { .api }
1235
/**
1236
 * Helper: Create run and poll until terminal state
1237
 * @param threadId - The thread ID
1238
 * @param body - Run configuration
1239
 * @param options - Options including pollIntervalMs
1240
 * @returns Promise<Run>
1241
 */
1242
createAndPoll(
1243
  threadId: string,
1244
  body: RunCreateParamsNonStreaming,
1245
  options?: RequestOptions & { pollIntervalMs?: number }
1246
): Promise<Run>;
1247
```
1248

1249
**Usage:**
1250

1251
```typescript
1252
const run = await client.beta.threads.runs.createAndPoll(
1253
  thread.id,
1254
  { assistant_id: assistant.id },
1255
  { pollIntervalMs: 500 }
1256
);
1257

1258
console.log(run.status); // Terminal state: completed, failed, etc.
1259

1260
if (run.status === "completed") {
1261
  const messages = await client.beta.threads.messages.list(thread.id);
1262
  console.log(messages.data[0].content[0].text.value);
1263
}
1264
```
1265

1266
##### createAndStream
1267

1268
```typescript { .api }
1269
/**
1270
 * Helper: Create and stream run with AssistantStream
1271
 * @param threadId - The thread ID
1272
 * @param body - Run configuration
1273
 * @returns AssistantStream
1274
 * @deprecated Use stream() instead
1275
 */
1276
createAndStream(
1277
  threadId: string,
1278
  body: RunCreateParamsBaseStream,
1279
  options?: RequestOptions
1280
): AssistantStream;
1281
```
1282

1283
##### poll
1284

1285
```typescript { .api }
1286
/**
1287
 * Helper: Poll run until terminal state
1288
 * @param runId - The run ID
1289
 * @param params - Thread ID parameter
1290
 * @param options - Options including pollIntervalMs
1291
 * @returns Promise<Run>
1292
 */
1293
poll(
1294
  runId: string,
1295
  params: RunRetrieveParams,
1296
  options?: RequestOptions & { pollIntervalMs?: number }
1297
): Promise<Run>;
1298
```
1299

1300
##### stream
1301

1302
```typescript { .api }
1303
/**
1304
 * Helper: Stream run with AssistantStream
1305
 * @param threadId - The thread ID
1306
 * @param body - Run configuration
1307
 * @returns AssistantStream
1308
 */
1309
stream(
1310
  threadId: string,
1311
  body: RunCreateParamsBaseStream,
1312
  options?: RequestOptions
1313
): AssistantStream;
1314
```
1315

1316
**Usage:**
1317

1318
```typescript
1319
const stream = client.beta.threads.runs.stream(thread.id, {
1320
  assistant_id: assistant.id
1321
});
1322

1323
stream
1324
  .on("textCreated", () => console.log("Text created"))
1325
  .on("textDelta", (delta, snapshot) => {
1326
    process.stdout.write(delta.value || "");
1327
  })
1328
  .on("messageDone", async (message) => {
1329
    console.log("\nMessage done:", message.id);
1330
  });
1331

1332
await stream.finalRun();
1333
```
1334

1335
##### submitToolOutputsAndPoll
1336

1337
```typescript { .api }
1338
/**
1339
 * Helper: Submit tool outputs and poll until terminal state
1340
 * @param runId - The run ID
1341
 * @param params - Tool outputs and thread ID
1342
 * @param options - Options including pollIntervalMs
1343
 * @returns Promise<Run>
1344
 */
1345
submitToolOutputsAndPoll(
1346
  runId: string,
1347
  params: RunSubmitToolOutputsParamsNonStreaming,
1348
  options?: RequestOptions & { pollIntervalMs?: number }
1349
): Promise<Run>;
1350
```
1351

1352
##### submitToolOutputsStream
1353

1354
```typescript { .api }
1355
/**
1356
 * Helper: Submit tool outputs and stream with AssistantStream
1357
 * @param runId - The run ID
1358
 * @param params - Tool outputs and thread ID
1359
 * @returns AssistantStream
1360
 */
1361
submitToolOutputsStream(
1362
  runId: string,
1363
  params: RunSubmitToolOutputsParamsStream,
1364
  options?: RequestOptions
1365
): AssistantStream;
1366
```
1367

1368
#### Types
1369

1370
##### Run
1371

1372
```typescript { .api }
1373
/**
1374
 * Represents an execution run on a thread
1375
 */
1376
interface Run {
1377
  /** The identifier */
1378
  id: string;
1379

1380
  /** Assistant ID used for this run */
1381
  assistant_id: string;
1382

1383
  /** When run was cancelled (Unix seconds) */
1384
  cancelled_at: number | null;
1385

1386
  /** When run was completed (Unix seconds) */
1387
  completed_at: number | null;
1388

1389
  /** Creation timestamp (Unix seconds) */
1390
  created_at: number;
1391

1392
  /** Expiration timestamp (Unix seconds) */
1393
  expires_at: number | null;
1394

1395
  /** When run failed (Unix seconds) */
1396
  failed_at: number | null;
1397

1398
  /** Incomplete details */
1399
  incomplete_details: Run.IncompleteDetails | null;
1400

1401
  /** Instructions used for this run */
1402
  instructions: string;
1403

1404
  /** Last error if any */
1405
  last_error: Run.LastError | null;
1406

1407
  /** Max completion tokens */
1408
  max_completion_tokens: number | null;
1409

1410
  /** Max prompt tokens */
1411
  max_prompt_tokens: number | null;
1412

1413
  /** Metadata */
1414
  metadata: Metadata | null;
1415

1416
  /** Model used */
1417
  model: string;
1418

1419
  /** Always 'thread.run' */
1420
  object: "thread.run";
1421

1422
  /** Whether parallel function calling is enabled */
1423
  parallel_tool_calls: boolean;
1424

1425
  /** Required action details if status is requires_action */
1426
  required_action: Run.RequiredAction | null;
1427

1428
  /** Response format */
1429
  response_format: AssistantResponseFormatOption | null;
1430

1431
  /** When run started (Unix seconds) */
1432
  started_at: number | null;
1433

1434
  /** Run status */
1435
  status: RunStatus;
1436

1437
  /** Parent thread ID */
1438
  thread_id: string;
1439

1440
  /** Tool choice configuration */
1441
  tool_choice: AssistantToolChoiceOption | null;
1442

1443
  /** Tools used */
1444
  tools: Array<AssistantTool>;
1445

1446
  /** Truncation strategy */
1447
  truncation_strategy: Run.TruncationStrategy | null;
1448

1449
  /** Usage statistics (null until terminal state) */
1450
  usage: Run.Usage | null;
1451

1452
  /** Sampling temperature */
1453
  temperature?: number | null;
1454

1455
  /** Nucleus sampling */
1456
  top_p?: number | null;
1457
}
1458

1459
namespace Run {
1460
  interface IncompleteDetails {
1461
    /** Why run is incomplete */
1462
    reason?: "max_completion_tokens" | "max_prompt_tokens";
1463
  }
1464

1465
  interface LastError {
1466
    /** Error code */
1467
    code: "server_error" | "rate_limit_exceeded" | "invalid_prompt";
1468

1469
    /** Error message */
1470
    message: string;
1471
  }
1472

1473
  interface RequiredAction {
1474
    /** Tool outputs required */
1475
    submit_tool_outputs: {
1476
      /** Tool calls needing outputs */
1477
      tool_calls: Array<RequiredActionFunctionToolCall>;
1478
    };
1479

1480
    /** Always 'submit_tool_outputs' */
1481
    type: "submit_tool_outputs";
1482
  }
1483

1484
  interface TruncationStrategy {
1485
    /** Truncation type */
1486
    type: "auto" | "last_messages";
1487

1488
    /** Number of recent messages to keep */
1489
    last_messages?: number | null;
1490
  }
1491

1492
  interface Usage {
1493
    /** Completion tokens used */
1494
    completion_tokens: number;
1495

1496
    /** Prompt tokens used */
1497
    prompt_tokens: number;
1498

1499
    /** Total tokens used */
1500
    total_tokens: number;
1501
  }
1502
}
1503
```
1504

1505
##### RunStatus
1506

1507
```typescript { .api }
1508
/**
1509
 * Run status values
1510
 */
1511
type RunStatus =
1512
  | "queued"
1513
  | "in_progress"
1514
  | "requires_action"
1515
  | "cancelling"
1516
  | "cancelled"
1517
  | "failed"
1518
  | "completed"
1519
  | "incomplete"
1520
  | "expired";
1521
```
1522

1523
##### RequiredActionFunctionToolCall
1524

1525
```typescript { .api }
1526
/**
1527
 * Function tool call requiring output
1528
 */
1529
interface RequiredActionFunctionToolCall {
1530
  /** Tool call ID (reference when submitting outputs) */
1531
  id: string;
1532

1533
  /** Function definition */
1534
  function: {
1535
    /** Arguments as JSON string */
1536
    arguments: string;
1537

1538
    /** Function name */
1539
    name: string;
1540
  };
1541

1542
  /** Always 'function' */
1543
  type: "function";
1544
}
1545
```
1546

1547
##### RunCreateParams
1548

1549
```typescript { .api }
1550
/**
1551
 * Parameters for creating a run
1552
 */
1553
interface RunCreateParamsBase {
1554
  /** Assistant ID to use */
1555
  assistant_id: string;
1556

1557
  /** Additional fields to include in response */
1558
  include?: Array<RunStepInclude>;
1559

1560
  /** Additional instructions appended to assistant instructions */
1561
  additional_instructions?: string | null;
1562

1563
  /** Additional messages added before run */
1564
  additional_messages?: Array<RunCreateParams.AdditionalMessage> | null;
1565

1566
  /** Override assistant instructions */
1567
  instructions?: string | null;
1568

1569
  /** Max completion tokens */
1570
  max_completion_tokens?: number | null;
1571

1572
  /** Max prompt tokens */
1573
  max_prompt_tokens?: number | null;
1574

1575
  /** Metadata */
1576
  metadata?: Metadata | null;
1577

1578
  /** Override model */
1579
  model?: string | ChatModel | null;
1580

1581
  /** Enable parallel function calling */
1582
  parallel_tool_calls?: boolean;
1583

1584
  /** Reasoning effort */
1585
  reasoning_effort?: ReasoningEffort | null;
1586

1587
  /** Response format */
1588
  response_format?: AssistantResponseFormatOption | null;
1589

1590
  /** Enable streaming */
1591
  stream?: boolean | null;
1592

1593
  /** Temperature */
1594
  temperature?: number | null;
1595

1596
  /** Tool choice */
1597
  tool_choice?: AssistantToolChoiceOption | null;
1598

1599
  /** Override tools */
1600
  tools?: Array<AssistantTool> | null;
1601

1602
  /** Top-p sampling */
1603
  top_p?: number | null;
1604

1605
  /** Truncation strategy */
1606
  truncation_strategy?: RunCreateParams.TruncationStrategy | null;
1607
}
1608

1609
type RunCreateParams =
1610
  | RunCreateParamsNonStreaming
1611
  | RunCreateParamsStreaming;
1612

1613
interface RunCreateParamsNonStreaming extends RunCreateParamsBase {
1614
  stream?: false | null;
1615
}
1616

1617
interface RunCreateParamsStreaming extends RunCreateParamsBase {
1618
  stream: true;
1619
}
1620
```
1621

1622
##### RunSubmitToolOutputsParams
1623

1624
```typescript { .api }
1625
/**
1626
 * Parameters for submitting tool outputs
1627
 */
1628
interface RunSubmitToolOutputsParamsBase {
1629
  /** Thread ID */
1630
  thread_id: string;
1631

1632
  /** Tool outputs */
1633
  tool_outputs: Array<RunSubmitToolOutputsParams.ToolOutput>;
1634

1635
  /** Enable streaming */
1636
  stream?: boolean | null;
1637
}
1638

1639
namespace RunSubmitToolOutputsParams {
1640
  interface ToolOutput {
1641
    /** Output value as string */
1642
    output?: string;
1643

1644
    /** Tool call ID */
1645
    tool_call_id?: string;
1646
  }
1647
}
1648

1649
type RunSubmitToolOutputsParams =
1650
  | RunSubmitToolOutputsParamsNonStreaming
1651
  | RunSubmitToolOutputsParamsStreaming;
1652
```
1653

1654
##### AssistantToolChoiceOption
1655

1656
```typescript { .api }
1657
/**
1658
 * Controls which tool is called
1659
 */
1660
type AssistantToolChoiceOption =
1661
  | "none"      // Model will not call tools
1662
  | "auto"      // Model can choose (default)
1663
  | "required"  // Model must call at least one tool
1664
  | AssistantToolChoice;
1665

1666
interface AssistantToolChoice {
1667
  /** Tool type */
1668
  type: "function" | "code_interpreter" | "file_search";
1669

1670
  /** Function name (if type is function) */
1671
  function?: {
1672
    name: string;
1673
  };
1674
}
1675
```
1676

1677
---
1678

1679
### Run Steps (`client.beta.threads.runs.steps`)
1680

1681
Access detailed step-by-step execution information for runs.
1682

1683
#### Methods
1684

1685
##### retrieve
1686

1687
```typescript { .api }
1688
/**
1689
 * Retrieve a run step
1690
 * @param stepID - The step ID
1691
 * @param params - Thread ID and run ID
1692
 * @returns Promise<RunStep>
1693
 */
1694
retrieve(
1695
  stepID: string,
1696
  params: StepRetrieveParams,
1697
  options?: RequestOptions
1698
): Promise<RunStep>;
1699
```
1700

1701
**Usage:**
1702

1703
```typescript
1704
const step = await client.beta.threads.runs.steps.retrieve(
1705
  stepId,
1706
  {
1707
    thread_id: thread.id,
1708
    run_id: run.id,
1709
    include: ["step_details.tool_calls[*].file_search.results[*].content"]
1710
  }
1711
);
1712

1713
console.log(step.type); // "message_creation" or "tool_calls"
1714
```
1715

1716
##### list
1717

1718
```typescript { .api }
1719
/**
1720
 * List steps for a run
1721
 * @param runID - The run ID
1722
 * @param params - Thread ID and pagination
1723
 * @returns PagePromise<RunStepsPage, RunStep>
1724
 */
1725
list(
1726
  runID: string,
1727
  params: StepListParams,
1728
  options?: RequestOptions
1729
): PagePromise<RunStepsPage, RunStep>;
1730
```
1731

1732
**Usage:**
1733

1734
```typescript
1735
for await (const step of client.beta.threads.runs.steps.list(run.id, {
1736
  thread_id: thread.id,
1737
  order: "asc"
1738
})) {
1739
  console.log(`Step ${step.id}: ${step.type} - ${step.status}`);
1740

1741
  if (step.type === "tool_calls") {
1742
    for (const toolCall of step.step_details.tool_calls) {
1743
      if (toolCall.type === "code_interpreter") {
1744
        console.log("Code:", toolCall.code_interpreter.input);
1745
        console.log("Outputs:", toolCall.code_interpreter.outputs);
1746
      }
1747
    }
1748
  }
1749
}
1750
```
1751

1752
#### Types
1753

1754
##### RunStep
1755

1756
```typescript { .api }
1757
/**
1758
 * Represents a step in execution of a run
1759
 */
1760
interface RunStep {
1761
  /** The identifier */
1762
  id: string;
1763

1764
  /** Associated assistant ID */
1765
  assistant_id: string;
1766

1767
  /** When cancelled (Unix seconds) */
1768
  cancelled_at: number | null;
1769

1770
  /** When completed (Unix seconds) */
1771
  completed_at: number | null;
1772

1773
  /** Creation timestamp (Unix seconds) */
1774
  created_at: number;
1775

1776
  /** When expired (Unix seconds) */
1777
  expired_at: number | null;
1778

1779
  /** When failed (Unix seconds) */
1780
  failed_at: number | null;
1781

1782
  /** Last error */
1783
  last_error: RunStep.LastError | null;
1784

1785
  /** Metadata */
1786
  metadata: Metadata | null;
1787

1788
  /** Always 'thread.run.step' */
1789
  object: "thread.run.step";
1790

1791
  /** Parent run ID */
1792
  run_id: string;
1793

1794
  /** Step status */
1795
  status: "in_progress" | "cancelled" | "failed" | "completed" | "expired";
1796

1797
  /** Step details */
1798
  step_details: MessageCreationStepDetails | ToolCallsStepDetails;
1799

1800
  /** Parent thread ID */
1801
  thread_id: string;
1802

1803
  /** Step type */
1804
  type: "message_creation" | "tool_calls";
1805

1806
  /** Usage statistics (null while in_progress) */
1807
  usage: RunStep.Usage | null;
1808
}
1809

1810
namespace RunStep {
1811
  interface LastError {
1812
    /** Error code */
1813
    code: "server_error" | "rate_limit_exceeded";
1814

1815
    /** Error message */
1816
    message: string;
1817
  }
1818

1819
  interface Usage {
1820
    /** Completion tokens */
1821
    completion_tokens: number;
1822

1823
    /** Prompt tokens */
1824
    prompt_tokens: number;
1825

1826
    /** Total tokens */
1827
    total_tokens: number;
1828
  }
1829
}
1830
```
1831

1832
##### MessageCreationStepDetails
1833

1834
```typescript { .api }
1835
/**
1836
 * Message creation step details
1837
 */
1838
interface MessageCreationStepDetails {
1839
  message_creation: {
1840
    /** ID of created message */
1841
    message_id: string;
1842
  };
1843

1844
  /** Always 'message_creation' */
1845
  type: "message_creation";
1846
}
1847
```
1848

1849
##### ToolCallsStepDetails
1850

1851
```typescript { .api }
1852
/**
1853
 * Tool calls step details
1854
 */
1855
interface ToolCallsStepDetails {
1856
  /** Tool calls in this step */
1857
  tool_calls: Array<ToolCall>;
1858

1859
  /** Always 'tool_calls' */
1860
  type: "tool_calls";
1861
}
1862
```
1863

1864
##### ToolCall
1865

1866
```typescript { .api }
1867
/**
1868
 * Tool call types
1869
 */
1870
type ToolCall =
1871
  | CodeInterpreterToolCall
1872
  | FileSearchToolCall
1873
  | FunctionToolCall;
1874

1875
/**
1876
 * Code interpreter tool call
1877
 */
1878
interface CodeInterpreterToolCall {
1879
  /** Tool call ID */
1880
  id: string;
1881

1882
  /** Code interpreter details */
1883
  code_interpreter: {
1884
    /** Input code */
1885
    input: string;
1886

1887
    /** Outputs (logs or images) */
1888
    outputs: Array<
1889
      | { type: "logs"; logs: string }
1890
      | { type: "image"; image: { file_id: string } }
1891
    >;
1892
  };
1893

1894
  /** Always 'code_interpreter' */
1895
  type: "code_interpreter";
1896
}
1897

1898
/**
1899
 * File search tool call
1900
 */
1901
interface FileSearchToolCall {
1902
  /** Tool call ID */
1903
  id: string;
1904

1905
  /** File search details */
1906
  file_search: {
1907
    /** Ranking options */
1908
    ranking_options?: {
1909
      /** Ranker type */
1910
      ranker: "auto" | "default_2024_08_21";
1911

1912
      /** Score threshold */
1913
      score_threshold: number;
1914
    };
1915

1916
    /** Search results */
1917
    results?: Array<{
1918
      /** File ID */
1919
      file_id: string;
1920

1921
      /** File name */
1922
      file_name: string;
1923

1924
      /** Relevance score */
1925
      score: number;
1926

1927
      /** Content (if requested) */
1928
      content?: Array<{ text?: string; type?: "text" }>;
1929
    }>;
1930
  };
1931

1932
  /** Always 'file_search' */
1933
  type: "file_search";
1934
}
1935

1936
/**
1937
 * Function tool call
1938
 */
1939
interface FunctionToolCall {
1940
  /** Tool call ID */
1941
  id: string;
1942

1943
  /** Function details */
1944
  function: {
1945
    /** Arguments */
1946
    arguments: string;
1947

1948
    /** Function name */
1949
    name: string;
1950

1951
    /** Output (null until submitted) */
1952
    output: string | null;
1953
  };
1954

1955
  /** Always 'function' */
1956
  type: "function";
1957
}
1958
```
1959

1960
##### RunStepDelta & RunStepDeltaEvent
1961

1962
```typescript { .api }
1963
/**
1964
 * Run step delta during streaming
1965
 */
1966
interface RunStepDelta {
1967
  /** Step details delta */
1968
  step_details?: RunStepDeltaMessageDelta | ToolCallDeltaObject;
1969
}
1970

1971
/**
1972
 * Run step delta event
1973
 */
1974
interface RunStepDeltaEvent {
1975
  /** Step ID */
1976
  id: string;
1977

1978
  /** The delta */
1979
  delta: RunStepDelta;
1980

1981
  /** Always 'thread.run.step.delta' */
1982
  object: "thread.run.step.delta";
1983
}
1984

1985
/**
1986
 * Tool call delta
1987
 */
1988
type ToolCallDelta =
1989
  | CodeInterpreterToolCallDelta
1990
  | FileSearchToolCallDelta
1991
  | FunctionToolCallDelta;
1992

1993
interface ToolCallDeltaObject {
1994
  /** Always 'tool_calls' */
1995
  type: "tool_calls";
1996

1997
  /** Tool call deltas */
1998
  tool_calls?: Array<ToolCallDelta>;
1999
}
2000
```
2001

2002
---
2003

2004
## Streaming with AssistantStream
2005

2006
The `AssistantStream` class provides a rich event-based interface for streaming runs.
2007

2008
### AssistantStream Class
2009

2010
```typescript { .api }
2011
/**
2012
 * Typed stream for assistant responses with event handlers
2013
 */
2014
class AssistantStream extends EventStream<AssistantStreamEvents>
2015
  implements AsyncIterable<AssistantStreamEvent> {
2016

2017
  /**
2018
   * Current event being processed
2019
   */
2020
  currentEvent(): AssistantStreamEvent | undefined;
2021

2022
  /**
2023
   * Current run snapshot
2024
   */
2025
  currentRun(): Run | undefined;
2026

2027
  /**
2028
   * Current message snapshot
2029
   */
2030
  currentMessageSnapshot(): Message | undefined;
2031

2032
  /**
2033
   * Current run step snapshot
2034
   */
2035
  currentRunStepSnapshot(): RunStep | undefined;
2036

2037
  /**
2038
   * Get final run steps after stream completes
2039
   */
2040
  finalRunSteps(): Promise<RunStep[]>;
2041

2042
  /**
2043
   * Get final messages after stream completes
2044
   */
2045
  finalMessages(): Promise<Message[]>;
2046

2047
  /**
2048
   * Get final run after stream completes
2049
   */
2050
  finalRun(): Promise<Run>;
2051

2052
  /**
2053
   * Create stream from ReadableStream
2054
   */
2055
  static fromReadableStream(stream: ReadableStream): AssistantStream;
2056

2057
  /**
2058
   * Convert to ReadableStream
2059
   */
2060
  toReadableStream(): ReadableStream;
2061
}
2062
```
2063

2064
### AssistantStreamEvents
2065

2066
```typescript { .api }
2067
/**
2068
 * Event handlers for AssistantStream
2069
 */
2070
interface AssistantStreamEvents {
2071
  /** Run state changes */
2072
  run: (run: Run) => void;
2073

2074
  /** Message lifecycle */
2075
  messageCreated: (message: Message) => void;
2076
  messageDelta: (message: MessageDelta, snapshot: Message) => void;
2077
  messageDone: (message: Message) => void;
2078

2079
  /** Run step lifecycle */
2080
  runStepCreated: (runStep: RunStep) => void;
2081
  runStepDelta: (delta: RunStepDelta, snapshot: RunStep) => void;
2082
  runStepDone: (runStep: RunStep, snapshot: RunStep) => void;
2083

2084
  /** Tool call lifecycle */
2085
  toolCallCreated: (toolCall: ToolCall) => void;
2086
  toolCallDelta: (delta: ToolCallDelta, snapshot: ToolCall) => void;
2087
  toolCallDone: (toolCall: ToolCall) => void;
2088

2089
  /** Text content lifecycle */
2090
  textCreated: (content: Text) => void;
2091
  textDelta: (delta: TextDelta, snapshot: Text) => void;
2092
  textDone: (content: Text, snapshot: Message) => void;
2093

2094
  /** Image files (not streamed) */
2095
  imageFileDone: (content: ImageFile, snapshot: Message) => void;
2096

2097
  /** Raw events */
2098
  event: (event: AssistantStreamEvent) => void;
2099

2100
  /** Stream lifecycle */
2101
  connect: () => void;
2102
  end: () => void;
2103
  abort: (error: Error) => void;
2104
  error: (error: Error) => void;
2105
}
2106
```
2107

2108
### AssistantStreamEvent Types
2109

2110
```typescript { .api }
2111
/**
2112
 * Union of all streaming event types
2113
 */
2114
type AssistantStreamEvent =
2115
  // Thread events
2116
  | ThreadCreated
2117
  // Run events
2118
  | ThreadRunCreated
2119
  | ThreadRunQueued
2120
  | ThreadRunInProgress
2121
  | ThreadRunRequiresAction
2122
  | ThreadRunCompleted
2123
  | ThreadRunIncomplete
2124
  | ThreadRunFailed
2125
  | ThreadRunCancelling
2126
  | ThreadRunCancelled
2127
  | ThreadRunExpired
2128
  // Step events
2129
  | ThreadRunStepCreated
2130
  | ThreadRunStepInProgress
2131
  | ThreadRunStepDelta
2132
  | ThreadRunStepCompleted
2133
  | ThreadRunStepFailed
2134
  | ThreadRunStepCancelled
2135
  | ThreadRunStepExpired
2136
  // Message events
2137
  | ThreadMessageCreated
2138
  | ThreadMessageInProgress
2139
  | ThreadMessageDelta
2140
  | ThreadMessageCompleted
2141
  | ThreadMessageIncomplete
2142
  // Error
2143
  | ErrorEvent;
2144

2145
/**
2146
 * Thread created event
2147
 */
2148
interface ThreadCreated {
2149
  data: Thread;
2150
  event: "thread.created";
2151
  enabled?: boolean;
2152
}
2153

2154
/**
2155
 * Run created event
2156
 */
2157
interface ThreadRunCreated {
2158
  data: Run;
2159
  event: "thread.run.created";
2160
}
2161

2162
/**
2163
 * Run queued event
2164
 */
2165
interface ThreadRunQueued {
2166
  data: Run;
2167
  event: "thread.run.queued";
2168
}
2169

2170
/**
2171
 * Run in progress event
2172
 */
2173
interface ThreadRunInProgress {
2174
  data: Run;
2175
  event: "thread.run.in_progress";
2176
}
2177

2178
/**
2179
 * Run requires action event
2180
 */
2181
interface ThreadRunRequiresAction {
2182
  data: Run;
2183
  event: "thread.run.requires_action";
2184
}
2185

2186
/**
2187
 * Run completed event
2188
 */
2189
interface ThreadRunCompleted {
2190
  data: Run;
2191
  event: "thread.run.completed";
2192
}
2193

2194
/**
2195
 * Run incomplete event
2196
 */
2197
interface ThreadRunIncomplete {
2198
  data: Run;
2199
  event: "thread.run.incomplete";
2200
}
2201

2202
/**
2203
 * Run failed event
2204
 */
2205
interface ThreadRunFailed {
2206
  data: Run;
2207
  event: "thread.run.failed";
2208
}
2209

2210
/**
2211
 * Run cancelling event
2212
 */
2213
interface ThreadRunCancelling {
2214
  data: Run;
2215
  event: "thread.run.cancelling";
2216
}
2217

2218
/**
2219
 * Run cancelled event
2220
 */
2221
interface ThreadRunCancelled {
2222
  data: Run;
2223
  event: "thread.run.cancelled";
2224
}
2225

2226
/**
2227
 * Run expired event
2228
 */
2229
interface ThreadRunExpired {
2230
  data: Run;
2231
  event: "thread.run.expired";
2232
}
2233

2234
/**
2235
 * Run step created event
2236
 */
2237
interface ThreadRunStepCreated {
2238
  data: RunStep;
2239
  event: "thread.run.step.created";
2240
}
2241

2242
/**
2243
 * Run step in progress event
2244
 */
2245
interface ThreadRunStepInProgress {
2246
  data: RunStep;
2247
  event: "thread.run.step.in_progress";
2248
}
2249

2250
/**
2251
 * Run step delta event (streaming changes)
2252
 */
2253
interface ThreadRunStepDelta {
2254
  data: RunStepDeltaEvent;
2255
  event: "thread.run.step.delta";
2256
}
2257

2258
/**
2259
 * Run step completed event
2260
 */
2261
interface ThreadRunStepCompleted {
2262
  data: RunStep;
2263
  event: "thread.run.step.completed";
2264
}
2265

2266
/**
2267
 * Run step failed event
2268
 */
2269
interface ThreadRunStepFailed {
2270
  data: RunStep;
2271
  event: "thread.run.step.failed";
2272
}
2273

2274
/**
2275
 * Run step cancelled event
2276
 */
2277
interface ThreadRunStepCancelled {
2278
  data: RunStep;
2279
  event: "thread.run.step.cancelled";
2280
}
2281

2282
/**
2283
 * Run step expired event
2284
 */
2285
interface ThreadRunStepExpired {
2286
  data: RunStep;
2287
  event: "thread.run.step.expired";
2288
}
2289

2290
/**
2291
 * Message created event
2292
 */
2293
interface ThreadMessageCreated {
2294
  data: Message;
2295
  event: "thread.message.created";
2296
}
2297

2298
/**
2299
 * Message in progress event
2300
 */
2301
interface ThreadMessageInProgress {
2302
  data: Message;
2303
  event: "thread.message.in_progress";
2304
}
2305

2306
/**
2307
 * Message delta event (streaming changes)
2308
 */
2309
interface ThreadMessageDelta {
2310
  data: MessageDeltaEvent;
2311
  event: "thread.message.delta";
2312
}
2313

2314
/**
2315
 * Message completed event
2316
 */
2317
interface ThreadMessageCompleted {
2318
  data: Message;
2319
  event: "thread.message.completed";
2320
}
2321

2322
/**
2323
 * Message incomplete event
2324
 */
2325
interface ThreadMessageIncomplete {
2326
  data: Message;
2327
  event: "thread.message.incomplete";
2328
}
2329

2330
/**
2331
 * Error event
2332
 */
2333
interface ErrorEvent {
2334
  data: ErrorObject;
2335
  event: "error";
2336
}
2337
```
2338

2339
## Complete Examples
2340

2341
### Basic Assistant Workflow
2342

2343
```typescript
2344
import OpenAI from "openai";
2345

2346
const client = new OpenAI();
2347

2348
// 1. Create an assistant
2349
const assistant = await client.beta.assistants.create({
2350
  model: "gpt-4o",
2351
  name: "Code Helper",
2352
  instructions: "You help debug code and write tests.",
2353
  tools: [{ type: "code_interpreter" }]
2354
});
2355

2356
// 2. Create a thread
2357
const thread = await client.beta.threads.create();
2358

2359
// 3. Add a message
2360
await client.beta.threads.messages.create(thread.id, {
2361
  role: "user",
2362
  content: "Write a function to calculate fibonacci numbers"
2363
});
2364

2365
// 4. Run the assistant and poll
2366
const run = await client.beta.threads.runs.createAndPoll(thread.id, {
2367
  assistant_id: assistant.id
2368
});
2369

2370
// 5. Retrieve messages
2371
if (run.status === "completed") {
2372
  const messages = await client.beta.threads.messages.list(thread.id);
2373

2374
  for (const message of messages.data.reverse()) {
2375
    console.log(`${message.role}: ${message.content[0].text.value}`);
2376
  }
2377
}
2378
```
2379

2380
### Streaming with Events
2381

2382
```typescript
2383
const stream = client.beta.threads.runs.stream(thread.id, {
2384
  assistant_id: assistant.id
2385
});
2386

2387
stream
2388
  .on("textCreated", () => console.log("\nassistant > "))
2389
  .on("textDelta", (delta, snapshot) => {
2390
    process.stdout.write(delta.value || "");
2391
  })
2392
  .on("textDone", (content, message) => {
2393
    console.log("\n");
2394
  })
2395
  .on("toolCallCreated", (toolCall) => {
2396
    console.log(`\nTool: ${toolCall.type}`);
2397
  })
2398
  .on("toolCallDelta", (delta, snapshot) => {
2399
    if (delta.type === "code_interpreter") {
2400
      if (delta.code_interpreter?.input) {
2401
        process.stdout.write(delta.code_interpreter.input);
2402
      }
2403
      if (delta.code_interpreter?.outputs) {
2404
        for (const output of delta.code_interpreter.outputs) {
2405
          if (output.type === "logs") {
2406
            console.log("\nLogs:", output.logs);
2407
          }
2408
        }
2409
      }
2410
    }
2411
  })
2412
  .on("messageDone", async (message) => {
2413
    // Check for citations
2414
    const textContent = message.content[0];
2415
    if (textContent.type === "text") {
2416
      for (const annotation of textContent.text.annotations) {
2417
        if (annotation.type === "file_citation") {
2418
          console.log(`\nCited file: ${annotation.file_citation.file_id}`);
2419
        }
2420
      }
2421
    }
2422
  });
2423

2424
const finalRun = await stream.finalRun();
2425
console.log("\nRun completed:", finalRun.status);
2426
```
2427

2428
### Function Calling
2429

2430
```typescript
2431
// Define function
2432
const functions = [
2433
  {
2434
    type: "function" as const,
2435
    function: {
2436
      name: "get_weather",
2437
      description: "Get current weather for a location",
2438
      parameters: {
2439
        type: "object",
2440
        properties: {
2441
          location: {
2442
            type: "string",
2443
            description: "City and state, e.g., San Francisco, CA"
2444
          },
2445
          unit: {
2446
            type: "string",
2447
            enum: ["celsius", "fahrenheit"]
2448
          }
2449
        },
2450
        required: ["location"]
2451
      }
2452
    }
2453
  }
2454
];
2455

2456
// Create assistant with function
2457
const assistant = await client.beta.assistants.create({
2458
  model: "gpt-4o",
2459
  tools: functions
2460
});
2461

2462
// Create thread and run
2463
const thread = await client.beta.threads.create({
2464
  messages: [
2465
    { role: "user", content: "What's the weather in Boston?" }
2466
  ]
2467
});
2468

2469
let run = await client.beta.threads.runs.create(thread.id, {
2470
  assistant_id: assistant.id
2471
});
2472

2473
// Poll until requires_action
2474
while (run.status === "queued" || run.status === "in_progress") {
2475
  await new Promise(resolve => setTimeout(resolve, 1000));
2476
  run = await client.beta.threads.runs.retrieve(run.id, {
2477
    thread_id: thread.id
2478
  });
2479
}
2480

2481
// Handle function calling
2482
if (run.status === "requires_action" &&
2483
    run.required_action?.type === "submit_tool_outputs") {
2484

2485
  const toolCalls = run.required_action.submit_tool_outputs.tool_calls;
2486
  const toolOutputs = [];
2487

2488
  for (const toolCall of toolCalls) {
2489
    if (toolCall.function.name === "get_weather") {
2490
      const args = JSON.parse(toolCall.function.arguments);
2491

2492
      // Call your actual weather API
2493
      const weatherData = await getWeather(args.location);
2494

2495
      toolOutputs.push({
2496
        tool_call_id: toolCall.id,
2497
        output: JSON.stringify(weatherData)
2498
      });
2499
    }
2500
  }
2501

2502
  // Submit outputs and poll
2503
  run = await client.beta.threads.runs.submitToolOutputsAndPoll(
2504
    run.id,
2505
    {
2506
      thread_id: thread.id,
2507
      tool_outputs: toolOutputs
2508
    }
2509
  );
2510
}
2511

2512
// Get final response
2513
if (run.status === "completed") {
2514
  const messages = await client.beta.threads.messages.list(thread.id);
2515
  console.log(messages.data[0].content[0].text.value);
2516
}
2517
```
2518

2519
### File Search with Assistants
2520

2521
```typescript
2522
// Upload files
2523
const file1 = await client.files.create({
2524
  file: fs.createReadStream("research-paper.pdf"),
2525
  purpose: "assistants"
2526
});
2527

2528
const file2 = await client.files.create({
2529
  file: fs.createReadStream("documentation.md"),
2530
  purpose: "assistants"
2531
});
2532

2533
// Create vector store
2534
const vectorStore = await client.vectorStores.create({
2535
  name: "Research Documents",
2536
  file_ids: [file1.id, file2.id]
2537
});
2538

2539
// Wait for file processing
2540
await client.vectorStores.files.poll(vectorStore.id, file1.id);
2541
await client.vectorStores.files.poll(vectorStore.id, file2.id);
2542

2543
// Create assistant with file search
2544
const assistant = await client.beta.assistants.create({
2545
  model: "gpt-4o",
2546
  name: "Research Assistant",
2547
  instructions: "You help answer questions based on provided documents.",
2548
  tools: [{ type: "file_search" }],
2549
  tool_resources: {
2550
    file_search: {
2551
      vector_store_ids: [vectorStore.id]
2552
    }
2553
  }
2554
});
2555

2556
// Create thread and run
2557
const thread = await client.beta.threads.create({
2558
  messages: [
2559
    {
2560
      role: "user",
2561
      content: "What are the main findings in the research paper?"
2562
    }
2563
  ]
2564
});
2565

2566
const run = await client.beta.threads.runs.createAndPoll(thread.id, {
2567
  assistant_id: assistant.id
2568
});
2569

2570
// Get response with citations
2571
if (run.status === "completed") {
2572
  const messages = await client.beta.threads.messages.list(thread.id);
2573
  const message = messages.data[0];
2574

2575
  if (message.content[0].type === "text") {
2576
    console.log(message.content[0].text.value);
2577

2578
    // Show citations
2579
    for (const annotation of message.content[0].text.annotations) {
2580
      if (annotation.type === "file_citation") {
2581
        console.log(`\nSource: File ${annotation.file_citation.file_id}`);
2582
        console.log(`Text: "${annotation.text}"`);
2583
      }
2584
    }
2585
  }
2586
}
2587
```
2588

2589
### Code Interpreter
2590

2591
```typescript
2592
// Upload data file
2593
const file = await client.files.create({
2594
  file: fs.createReadStream("sales-data.csv"),
2595
  purpose: "assistants"
2596
});
2597

2598
// Create assistant
2599
const assistant = await client.beta.assistants.create({
2600
  model: "gpt-4o",
2601
  name: "Data Analyst",
2602
  instructions: "You analyze data and create visualizations.",
2603
  tools: [{ type: "code_interpreter" }],
2604
  tool_resources: {
2605
    code_interpreter: {
2606
      file_ids: [file.id]
2607
    }
2608
  }
2609
});
2610

2611
// Stream the analysis
2612
const stream = client.beta.threads.runs.stream(thread.id, {
2613
  assistant_id: assistant.id
2614
});
2615

2616
stream
2617
  .on("toolCallCreated", (toolCall) => {
2618
    if (toolCall.type === "code_interpreter") {
2619
      console.log("\nRunning code...");
2620
    }
2621
  })
2622
  .on("toolCallDelta", (delta, snapshot) => {
2623
    if (delta.type === "code_interpreter") {
2624
      if (delta.code_interpreter?.input) {
2625
        console.log(delta.code_interpreter.input);
2626
      }
2627
      if (delta.code_interpreter?.outputs) {
2628
        for (const output of delta.code_interpreter.outputs) {
2629
          if (output.type === "logs") {
2630
            console.log("Output:", output.logs);
2631
          } else if (output.type === "image") {
2632
            console.log("Image generated:", output.image?.file_id);
2633
          }
2634
        }
2635
      }
2636
    }
2637
  });
2638

2639
await stream.finalRun();
2640
```
2641

2642
### Create and Run in One Step
2643

2644
```typescript
2645
// Create thread and run together
2646
const run = await client.beta.threads.createAndRunPoll({
2647
  assistant_id: assistant.id,
2648
  thread: {
2649
    messages: [
2650
      {
2651
        role: "user",
2652
        content: "Explain machine learning in simple terms",
2653
        attachments: [
2654
          {
2655
            file_id: "file-123",
2656
            tools: [{ type: "file_search" }]
2657
          }
2658
        ]
2659
      }
2660
    ],
2661
    metadata: { conversation_id: "conv-456" }
2662
  },
2663
  instructions: "Use simple language suitable for beginners",
2664
  temperature: 0.7,
2665
  tool_choice: "auto"
2666
});
2667

2668
console.log("Thread ID:", run.thread_id);
2669
console.log("Status:", run.status);
2670

2671
// Retrieve messages
2672
const messages = await client.beta.threads.messages.list(run.thread_id);
2673
```
2674

2675
### Error Handling
2676

2677
```typescript
2678
try {
2679
  const run = await client.beta.threads.runs.createAndPoll(thread.id, {
2680
    assistant_id: assistant.id
2681
  });
2682

2683
  // Check run status
2684
  switch (run.status) {
2685
    case "completed":
2686
      console.log("Success!");
2687
      break;
2688

2689
    case "failed":
2690
      console.error("Run failed:", run.last_error);
2691
      break;
2692

2693
    case "incomplete":
2694
      console.warn("Run incomplete:", run.incomplete_details);
2695
      break;
2696

2697
    case "expired":
2698
      console.error("Run expired");
2699
      break;
2700

2701
    case "requires_action":
2702
      console.log("Action required");
2703
      // Handle function calling
2704
      break;
2705
  }
2706
} catch (error) {
2707
  if (error instanceof OpenAI.APIError) {
2708
    console.error("API Error:", error.message);
2709
    console.error("Status:", error.status);
2710
    console.error("Type:", error.type);
2711
  } else {
2712
    console.error("Unexpected error:", error);
2713
  }
2714
}
2715
```
2716

2717
### Streaming with Async Iteration
2718

2719
```typescript
2720
const stream = await client.beta.threads.runs.create(thread.id, {
2721
  assistant_id: assistant.id,
2722
  stream: true
2723
});
2724

2725
for await (const event of stream) {
2726
  switch (event.event) {
2727
    case "thread.run.created":
2728
      console.log("Run created:", event.data.id);
2729
      break;
2730

2731
    case "thread.message.delta":
2732
      const delta = event.data.delta.content?.[0];
2733
      if (delta?.type === "text" && delta.text?.value) {
2734
        process.stdout.write(delta.text.value);
2735
      }
2736
      break;
2737

2738
    case "thread.run.step.delta":
2739
      const stepDelta = event.data.delta.step_details;
2740
      if (stepDelta?.type === "tool_calls") {
2741
        const toolCall = stepDelta.tool_calls?.[0];
2742
        if (toolCall?.type === "code_interpreter") {
2743
          console.log("\nCode:", toolCall.code_interpreter?.input);
2744
        }
2745
      }
2746
      break;
2747

2748
    case "thread.run.completed":
2749
      console.log("\nRun completed");
2750
      break;
2751

2752
    case "error":
2753
      console.error("Error:", event.data);
2754
      break;
2755
  }
2756
}
2757
```
2758

2759
## Best Practices
2760

2761
### Thread Management
2762

2763
```typescript
2764
// Reuse threads for conversations
2765
const thread = await client.beta.threads.create({
2766
  metadata: { user_id: "user-123", session_start: Date.now() }
2767
});
2768

2769
// Add messages over time
2770
await client.beta.threads.messages.create(thread.id, {
2771
  role: "user",
2772
  content: "First question"
2773
});
2774

2775
const run1 = await client.beta.threads.runs.createAndPoll(thread.id, {
2776
  assistant_id: assistant.id
2777
});
2778

2779
// Continue conversation in same thread
2780
await client.beta.threads.messages.create(thread.id, {
2781
  role: "user",
2782
  content: "Follow-up question"
2783
});
2784

2785
const run2 = await client.beta.threads.runs.createAndPoll(thread.id, {
2786
  assistant_id: assistant.id
2787
});
2788

2789
// Clean up when done
2790
await client.beta.threads.delete(thread.id);
2791
```
2792

2793
### Token Management
2794

2795
```typescript
2796
// Set token limits
2797
const run = await client.beta.threads.runs.create(thread.id, {
2798
  assistant_id: assistant.id,
2799
  max_prompt_tokens: 5000,
2800
  max_completion_tokens: 1000,
2801
  truncation_strategy: {
2802
    type: "last_messages",
2803
    last_messages: 10
2804
  }
2805
});
2806

2807
// Check usage
2808
if (run.status === "completed" && run.usage) {
2809
  console.log(`Tokens used: ${run.usage.total_tokens}`);
2810
  console.log(`  Prompt: ${run.usage.prompt_tokens}`);
2811
  console.log(`  Completion: ${run.usage.completion_tokens}`);
2812
}
2813
```
2814

2815
### Metadata and Organization
2816

2817
```typescript
2818
// Use metadata for tracking
2819
const assistant = await client.beta.assistants.create({
2820
  model: "gpt-4o",
2821
  metadata: {
2822
    version: "2.0",
2823
    department: "support",
2824
    created_by: "admin@example.com"
2825
  }
2826
});
2827

2828
const thread = await client.beta.threads.create({
2829
  metadata: {
2830
    user_id: "user-456",
2831
    conversation_type: "support",
2832
    priority: "high"
2833
  }
2834
});
2835

2836
// Query by metadata (when listing)
2837
for await (const assistant of client.beta.assistants.list()) {
2838
  if (assistant.metadata?.department === "support") {
2839
    console.log("Support assistant:", assistant.name);
2840
  }
2841
}
2842
```
2843

2844
### Polling Configuration
2845

2846
```typescript
2847
// Custom poll interval
2848
const run = await client.beta.threads.runs.createAndPoll(
2849
  thread.id,
2850
  { assistant_id: assistant.id },
2851
  {
2852
    pollIntervalMs: 500,  // Poll every 500ms
2853
    timeout: 60000        // 60 second timeout
2854
  }
2855
);
2856

2857
// The server may suggest poll intervals via openai-poll-after-ms header
2858
// The SDK automatically respects these suggestions
2859
```
2860

2861
## API Reference Summary
2862

2863
### Resource Hierarchy
2864

2865
```
2866
client.beta.assistants
2867
  ├── create(params)
2868
  ├── retrieve(id)
2869
  ├── update(id, params)
2870
  ├── list(params?)
2871
  └── delete(id)
2872

2873
client.beta.threads
2874
  ├── create(params?)
2875
  ├── retrieve(id)
2876
  ├── update(id, params)
2877
  ├── delete(id)
2878
  ├── createAndRun(params)
2879
  ├── createAndRunPoll(params, options)
2880
  ├── createAndRunStream(params, options)
2881
  │
2882
  ├── messages
2883
  │   ├── create(threadId, params)
2884
  │   ├── retrieve(messageId, params)
2885
  │   ├── update(messageId, params)
2886
  │   ├── list(threadId, params?)
2887
  │   └── delete(messageId, params)
2888
  │
2889
  └── runs
2890
      ├── create(threadId, params)
2891
      ├── retrieve(runId, params)
2892
      ├── update(runId, params)
2893
      ├── list(threadId, params?)
2894
      ├── cancel(runId, params)
2895
      ├── submitToolOutputs(runId, params)
2896
      ├── createAndPoll(threadId, params, options)
2897
      ├── createAndStream(threadId, params, options)
2898
      ├── poll(runId, params, options)
2899
      ├── stream(threadId, params, options)
2900
      ├── submitToolOutputsAndPoll(runId, params, options)
2901
      ├── submitToolOutputsStream(runId, params, options)
2902
      │
2903
      └── steps
2904
          ├── retrieve(stepId, params)
2905
          └── list(runId, params)
2906
```
2907

2908
### Type Summary
2909

2910
Core types: `Assistant`, `Thread`, `Message`, `Run`, `RunStep`
2911

2912
Tool types: `CodeInterpreterTool`, `FileSearchTool`, `FunctionTool`
2913

2914
Content types: `TextContentBlock`, `ImageFileContentBlock`, `ImageURLContentBlock`, `RefusalContentBlock`
2915

2916
Annotation types: `FileCitationAnnotation`, `FilePathAnnotation`
2917

2918
Stream event types: 20+ event interfaces in `AssistantStreamEvent` union
2919

2920
Delta types: `MessageDelta`, `RunStepDelta`, `TextDelta`, `ToolCallDelta`
2921

2922
Status types: `RunStatus`, message status, step status
2923

2924
Streaming: `AssistantStream`, `AssistantStreamEvents`, event interfaces
2925

2926
## Notes
2927

2928
- The Assistants API is marked as **deprecated** in favor of the Responses API but remains fully functional
2929
- All API methods include `'OpenAI-Beta': 'assistants=v2'` header automatically
2930
- Threads maintain conversation history automatically
2931
- Runs can be polled or streamed
2932
- File processing (code interpreter, file search) happens asynchronously
2933
- Helper methods (`createAndPoll`, `stream`, etc.) simplify common workflows
2934
- Token limits can be set per-run and are enforced across multiple turns
2935
- Streaming provides granular events for text, tool calls, and status changes
2936
- Function calling requires a polling loop to handle `requires_action` status
2937
- Metadata supports up to 16 key-value pairs per object
2938
- The SDK respects server-suggested poll intervals for optimal performance
2939