diff --git a/en/python/resources/beta/subresources/assistants/index.md b/en/python/resources/beta/subresources/assistants/index.md deleted file mode 100644 index ce8c42e..0000000 --- a/en/python/resources/beta/subresources/assistants/index.md +++ /dev/null @@ -1,5857 +0,0 @@ -# Assistants - -## List assistants - -`beta.assistants.list(AssistantListParams**kwargs) -> SyncCursorPage[Assistant]` - -**get** `/assistants` - -Returns a list of assistants. - -### Parameters - -- `after: Optional[str]` - - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - -- `before: Optional[str]` - - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - -- `limit: Optional[int]` - - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - -- `order: Optional[Literal["asc", "desc"]]` - - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - - `"asc"` - - - `"desc"` - -### Returns - -- `class Assistant: …` - - Represents an `assistant` that can call the model and use tools. - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the assistant was created. - - - `description: Optional[str]` - - The description of the assistant. The maximum length is 512 characters. - - - `instructions: Optional[str]` - - The system instructions that the assistant uses. The maximum length is 256,000 characters. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `model: str` - - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - - `name: Optional[str]` - - The name of the assistant. The maximum length is 256 characters. - - - `object: Literal["assistant"]` - - The object type, which is always `assistant`. - - - `"assistant"` - - - `tools: List[AssistantTool]` - - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - - - `response_format: Optional[AssistantResponseFormatOption]` - - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - - `Literal["auto"]` - - `auto` is the default value - - - `"auto"` - - - `class ResponseFormatText: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class ResponseFormatJSONObject: …` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `type: Literal["json_object"]` - - The type of response format being defined. Always `json_object`. - - - `"json_object"` - - - `class ResponseFormatJSONSchema: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_schema: JSONSchema` - - Structured Outputs configuration options, including a JSON Schema. - - - `name: str` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `schema: Optional[Dict[str, object]]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - - - `temperature: Optional[float]` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - - `tool_resources: Optional[ToolResources]` - - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - - `file_ids: Optional[List[str]]` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: Optional[ToolResourcesFileSearch]` - - - `vector_store_ids: Optional[List[str]]` - - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - - `top_p: Optional[float]` - - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - We generally recommend altering this or temperature but not both. - -### Example - -```python -import os -from openai import OpenAI - -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -page = client.beta.assistants.list() -page = page.data[0] -print(page.id) -``` - -#### Response - -```json -{ - "data": [ - { - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - { - "type": "code_interpreter" - } - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 - } - ], - "first_id": "asst_abc123", - "has_more": false, - "last_id": "asst_abc456", - "object": "list" -} -``` - -### Example - -```python -from openai import OpenAI -client = OpenAI() - -my_assistants = client.beta.assistants.list( - order="desc", - limit="20", -) -print(my_assistants.data) -``` - -#### Response - -```json -{ - "object": "list", - "data": [ - { - "id": "asst_abc123", - "object": "assistant", - "created_at": 1698982736, - "name": "Coding Tutor", - "description": null, - "model": "gpt-4o", - "instructions": "You are a helpful assistant designed to make me better at coding!", - "tools": [], - "tool_resources": {}, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - }, - { - "id": "asst_abc456", - "object": "assistant", - "created_at": 1698982718, - "name": "My Assistant", - "description": null, - "model": "gpt-4o", - "instructions": "You are a helpful assistant designed to make me better at coding!", - "tools": [], - "tool_resources": {}, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - }, - { - "id": "asst_abc789", - "object": "assistant", - "created_at": 1698982643, - "name": null, - "description": null, - "model": "gpt-4o", - "instructions": null, - "tools": [], - "tool_resources": {}, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - } - ], - "first_id": "asst_abc123", - "last_id": "asst_abc789", - "has_more": false -} -``` - -## Create assistant - -`beta.assistants.create(AssistantCreateParams**kwargs) -> Assistant` - -**post** `/assistants` - -Create an assistant with a model and instructions. - -### Parameters - -- `model: Union[str, ChatModel]` - - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - - `str` - - - `Literal["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", 75 more]` - - - `"gpt-5.4"` - - - `"gpt-5.4-mini"` - - - `"gpt-5.4-nano"` - - - `"gpt-5.4-mini-2026-03-17"` - - - `"gpt-5.4-nano-2026-03-17"` - - - `"gpt-5.3-chat-latest"` - - - `"gpt-5.2"` - - - `"gpt-5.2-2025-12-11"` - - - `"gpt-5.2-chat-latest"` - - - `"gpt-5.2-pro"` - - - `"gpt-5.2-pro-2025-12-11"` - - - `"gpt-5.1"` - - - `"gpt-5.1-2025-11-13"` - - - `"gpt-5.1-codex"` - - - `"gpt-5.1-mini"` - - - `"gpt-5.1-chat-latest"` - - - `"gpt-5"` - - - `"gpt-5-mini"` - - - `"gpt-5-nano"` - - - `"gpt-5-2025-08-07"` - - - `"gpt-5-mini-2025-08-07"` - - - `"gpt-5-nano-2025-08-07"` - - - `"gpt-5-chat-latest"` - - - `"gpt-4.1"` - - - `"gpt-4.1-mini"` - - - `"gpt-4.1-nano"` - - - `"gpt-4.1-2025-04-14"` - - - `"gpt-4.1-mini-2025-04-14"` - - - `"gpt-4.1-nano-2025-04-14"` - - - `"o4-mini"` - - - `"o4-mini-2025-04-16"` - - - `"o3"` - - - `"o3-2025-04-16"` - - - `"o3-mini"` - - - `"o3-mini-2025-01-31"` - - - `"o1"` - - - `"o1-2024-12-17"` - - - `"o1-preview"` - - - `"o1-preview-2024-09-12"` - - - `"o1-mini"` - - - `"o1-mini-2024-09-12"` - - - `"gpt-4o"` - - - `"gpt-4o-2024-11-20"` - - - `"gpt-4o-2024-08-06"` - - - `"gpt-4o-2024-05-13"` - - - `"gpt-4o-audio-preview"` - - - `"gpt-4o-audio-preview-2024-10-01"` - - - `"gpt-4o-audio-preview-2024-12-17"` - - - `"gpt-4o-audio-preview-2025-06-03"` - - - `"gpt-4o-mini-audio-preview"` - - - `"gpt-4o-mini-audio-preview-2024-12-17"` - - - `"gpt-4o-search-preview"` - - - `"gpt-4o-mini-search-preview"` - - - `"gpt-4o-search-preview-2025-03-11"` - - - `"gpt-4o-mini-search-preview-2025-03-11"` - - - `"chatgpt-4o-latest"` - - - `"codex-mini-latest"` - - - `"gpt-4o-mini"` - - - `"gpt-4o-mini-2024-07-18"` - - - `"gpt-4-turbo"` - - - `"gpt-4-turbo-2024-04-09"` - - - `"gpt-4-0125-preview"` - - - `"gpt-4-turbo-preview"` - - - `"gpt-4-1106-preview"` - - - `"gpt-4-vision-preview"` - - - `"gpt-4"` - - - `"gpt-4-0314"` - - - `"gpt-4-0613"` - - - `"gpt-4-32k"` - - - `"gpt-4-32k-0314"` - - - `"gpt-4-32k-0613"` - - - `"gpt-3.5-turbo"` - - - `"gpt-3.5-turbo-16k"` - - - `"gpt-3.5-turbo-0301"` - - - `"gpt-3.5-turbo-0613"` - - - `"gpt-3.5-turbo-1106"` - - - `"gpt-3.5-turbo-0125"` - - - `"gpt-3.5-turbo-16k-0613"` - -- `description: Optional[str]` - - The description of the assistant. The maximum length is 512 characters. - -- `instructions: Optional[str]` - - The system instructions that the assistant uses. The maximum length is 256,000 characters. - -- `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - -- `name: Optional[str]` - - The name of the assistant. The maximum length is 256 characters. - -- `reasoning_effort: Optional[ReasoningEffort]` - - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. - - - `"none"` - - - `"minimal"` - - - `"low"` - - - `"medium"` - - - `"high"` - - - `"xhigh"` - -- `response_format: Optional[AssistantResponseFormatOptionParam]` - - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - - `Literal["auto"]` - - `auto` is the default value - - - `"auto"` - - - `class ResponseFormatText: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class ResponseFormatJSONObject: …` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `type: Literal["json_object"]` - - The type of response format being defined. Always `json_object`. - - - `"json_object"` - - - `class ResponseFormatJSONSchema: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_schema: JSONSchema` - - Structured Outputs configuration options, including a JSON Schema. - - - `name: str` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `schema: Optional[Dict[str, object]]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - -- `temperature: Optional[float]` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - -- `tool_resources: Optional[ToolResources]` - - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - - `file_ids: Optional[Sequence[str]]` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: Optional[ToolResourcesFileSearch]` - - - `vector_store_ids: Optional[Sequence[str]]` - - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - - `vector_stores: Optional[Iterable[ToolResourcesFileSearchVectorStore]]` - - A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - - `chunking_strategy: Optional[ToolResourcesFileSearchVectorStoreChunkingStrategy]` - - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - - `class ToolResourcesFileSearchVectorStoreChunkingStrategyAuto: …` - - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - - - `type: Literal["auto"]` - - Always `auto`. - - - `"auto"` - - - `class ToolResourcesFileSearchVectorStoreChunkingStrategyStatic: …` - - - `static: ToolResourcesFileSearchVectorStoreChunkingStrategyStaticStatic` - - - `chunk_overlap_tokens: int` - - The number of tokens that overlap between chunks. The default value is `400`. - - Note that the overlap must not exceed half of `max_chunk_size_tokens`. - - - `max_chunk_size_tokens: int` - - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - - `type: Literal["static"]` - - Always `static`. - - - `"static"` - - - `file_ids: Optional[Sequence[str]]` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - -- `tools: Optional[Iterable[AssistantToolParam]]` - - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - -- `top_p: Optional[float]` - - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - We generally recommend altering this or temperature but not both. - -### Returns - -- `class Assistant: …` - - Represents an `assistant` that can call the model and use tools. - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the assistant was created. - - - `description: Optional[str]` - - The description of the assistant. The maximum length is 512 characters. - - - `instructions: Optional[str]` - - The system instructions that the assistant uses. The maximum length is 256,000 characters. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `model: str` - - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - - `name: Optional[str]` - - The name of the assistant. The maximum length is 256 characters. - - - `object: Literal["assistant"]` - - The object type, which is always `assistant`. - - - `"assistant"` - - - `tools: List[AssistantTool]` - - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - - - `response_format: Optional[AssistantResponseFormatOption]` - - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - - `Literal["auto"]` - - `auto` is the default value - - - `"auto"` - - - `class ResponseFormatText: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class ResponseFormatJSONObject: …` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `type: Literal["json_object"]` - - The type of response format being defined. Always `json_object`. - - - `"json_object"` - - - `class ResponseFormatJSONSchema: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_schema: JSONSchema` - - Structured Outputs configuration options, including a JSON Schema. - - - `name: str` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `schema: Optional[Dict[str, object]]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - - - `temperature: Optional[float]` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - - `tool_resources: Optional[ToolResources]` - - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - - `file_ids: Optional[List[str]]` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: Optional[ToolResourcesFileSearch]` - - - `vector_store_ids: Optional[List[str]]` - - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - - `top_p: Optional[float]` - - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - We generally recommend altering this or temperature but not both. - -### Example - -```python -import os -from openai import OpenAI - -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -assistant = client.beta.assistants.create( - model="gpt-4o", -) -print(assistant.id) -``` - -#### Response - -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - { - "type": "code_interpreter" - } - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` - -### Code Interpreter - -```python -from openai import OpenAI -client = OpenAI() - -my_assistant = client.beta.assistants.create( - instructions="You are a personal math tutor. When asked a question, write and run Python code to answer the question.", - name="Math Tutor", - tools=[{"type": "code_interpreter"}], - model="gpt-4o", -) -print(my_assistant) -``` - -#### Response - -```json -{ - "id": "asst_abc123", - "object": "assistant", - "created_at": 1698984975, - "name": "Math Tutor", - "description": null, - "model": "gpt-4o", - "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", - "tools": [ - { - "type": "code_interpreter" - } - ], - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" -} -``` - -### Files - -```python -from openai import OpenAI -client = OpenAI() - -my_assistant = client.beta.assistants.create( - instructions="You are an HR bot, and you have access to files to answer employee questions about company policies.", - name="HR Helper", - tools=[{"type": "file_search"}], - tool_resources={"file_search": {"vector_store_ids": ["vs_123"]}}, - model="gpt-4o" -) -print(my_assistant) -``` - -#### Response - -```json -{ - "id": "asst_abc123", - "object": "assistant", - "created_at": 1699009403, - "name": "HR Helper", - "description": null, - "model": "gpt-4o", - "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", - "tools": [ - { - "type": "file_search" - } - ], - "tool_resources": { - "file_search": { - "vector_store_ids": ["vs_123"] - } - }, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" -} -``` - -## Retrieve assistant - -`beta.assistants.retrieve(strassistant_id) -> Assistant` - -**get** `/assistants/{assistant_id}` - -Retrieves an assistant. - -### Parameters - -- `assistant_id: str` - -### Returns - -- `class Assistant: …` - - Represents an `assistant` that can call the model and use tools. - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the assistant was created. - - - `description: Optional[str]` - - The description of the assistant. The maximum length is 512 characters. - - - `instructions: Optional[str]` - - The system instructions that the assistant uses. The maximum length is 256,000 characters. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `model: str` - - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - - `name: Optional[str]` - - The name of the assistant. The maximum length is 256 characters. - - - `object: Literal["assistant"]` - - The object type, which is always `assistant`. - - - `"assistant"` - - - `tools: List[AssistantTool]` - - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - - - `response_format: Optional[AssistantResponseFormatOption]` - - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - - `Literal["auto"]` - - `auto` is the default value - - - `"auto"` - - - `class ResponseFormatText: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class ResponseFormatJSONObject: …` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `type: Literal["json_object"]` - - The type of response format being defined. Always `json_object`. - - - `"json_object"` - - - `class ResponseFormatJSONSchema: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_schema: JSONSchema` - - Structured Outputs configuration options, including a JSON Schema. - - - `name: str` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `schema: Optional[Dict[str, object]]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - - - `temperature: Optional[float]` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - - `tool_resources: Optional[ToolResources]` - - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - - `file_ids: Optional[List[str]]` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: Optional[ToolResourcesFileSearch]` - - - `vector_store_ids: Optional[List[str]]` - - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - - `top_p: Optional[float]` - - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - We generally recommend altering this or temperature but not both. - -### Example - -```python -import os -from openai import OpenAI - -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -assistant = client.beta.assistants.retrieve( - "assistant_id", -) -print(assistant.id) -``` - -#### Response - -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - { - "type": "code_interpreter" - } - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` - -### Example - -```python -from openai import OpenAI -client = OpenAI() - -my_assistant = client.beta.assistants.retrieve("asst_abc123") -print(my_assistant) -``` - -#### Response - -```json -{ - "id": "asst_abc123", - "object": "assistant", - "created_at": 1699009709, - "name": "HR Helper", - "description": null, - "model": "gpt-4o", - "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", - "tools": [ - { - "type": "file_search" - } - ], - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" -} -``` - -## Modify assistant - -`beta.assistants.update(strassistant_id, AssistantUpdateParams**kwargs) -> Assistant` - -**post** `/assistants/{assistant_id}` - -Modifies an assistant. - -### Parameters - -- `assistant_id: str` - -- `description: Optional[str]` - - The description of the assistant. The maximum length is 512 characters. - -- `instructions: Optional[str]` - - The system instructions that the assistant uses. The maximum length is 256,000 characters. - -- `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - -- `model: Optional[Union[str, Literal["gpt-5", "gpt-5-mini", "gpt-5-nano", 39 more]]]` - - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - - `str` - - - `Literal["gpt-5", "gpt-5-mini", "gpt-5-nano", 39 more]` - - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - - `"gpt-5"` - - - `"gpt-5-mini"` - - - `"gpt-5-nano"` - - - `"gpt-5-2025-08-07"` - - - `"gpt-5-mini-2025-08-07"` - - - `"gpt-5-nano-2025-08-07"` - - - `"gpt-4.1"` - - - `"gpt-4.1-mini"` - - - `"gpt-4.1-nano"` - - - `"gpt-4.1-2025-04-14"` - - - `"gpt-4.1-mini-2025-04-14"` - - - `"gpt-4.1-nano-2025-04-14"` - - - `"o3-mini"` - - - `"o3-mini-2025-01-31"` - - - `"o1"` - - - `"o1-2024-12-17"` - - - `"gpt-4o"` - - - `"gpt-4o-2024-11-20"` - - - `"gpt-4o-2024-08-06"` - - - `"gpt-4o-2024-05-13"` - - - `"gpt-4o-mini"` - - - `"gpt-4o-mini-2024-07-18"` - - - `"gpt-4.5-preview"` - - - `"gpt-4.5-preview-2025-02-27"` - - - `"gpt-4-turbo"` - - - `"gpt-4-turbo-2024-04-09"` - - - `"gpt-4-0125-preview"` - - - `"gpt-4-turbo-preview"` - - - `"gpt-4-1106-preview"` - - - `"gpt-4-vision-preview"` - - - `"gpt-4"` - - - `"gpt-4-0314"` - - - `"gpt-4-0613"` - - - `"gpt-4-32k"` - - - `"gpt-4-32k-0314"` - - - `"gpt-4-32k-0613"` - - - `"gpt-3.5-turbo"` - - - `"gpt-3.5-turbo-16k"` - - - `"gpt-3.5-turbo-0613"` - - - `"gpt-3.5-turbo-1106"` - - - `"gpt-3.5-turbo-0125"` - - - `"gpt-3.5-turbo-16k-0613"` - -- `name: Optional[str]` - - The name of the assistant. The maximum length is 256 characters. - -- `reasoning_effort: Optional[ReasoningEffort]` - - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - - - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - - `xhigh` is supported for all models after `gpt-5.1-codex-max`. - - - `"none"` - - - `"minimal"` - - - `"low"` - - - `"medium"` - - - `"high"` - - - `"xhigh"` - -- `response_format: Optional[AssistantResponseFormatOptionParam]` - - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - - `Literal["auto"]` - - `auto` is the default value - - - `"auto"` - - - `class ResponseFormatText: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class ResponseFormatJSONObject: …` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `type: Literal["json_object"]` - - The type of response format being defined. Always `json_object`. - - - `"json_object"` - - - `class ResponseFormatJSONSchema: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_schema: JSONSchema` - - Structured Outputs configuration options, including a JSON Schema. - - - `name: str` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `schema: Optional[Dict[str, object]]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - -- `temperature: Optional[float]` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - -- `tool_resources: Optional[ToolResources]` - - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - - `file_ids: Optional[Sequence[str]]` - - Overrides the list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: Optional[ToolResourcesFileSearch]` - - - `vector_store_ids: Optional[Sequence[str]]` - - Overrides the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - -- `tools: Optional[Iterable[AssistantToolParam]]` - - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - -- `top_p: Optional[float]` - - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - We generally recommend altering this or temperature but not both. - -### Returns - -- `class Assistant: …` - - Represents an `assistant` that can call the model and use tools. - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the assistant was created. - - - `description: Optional[str]` - - The description of the assistant. The maximum length is 512 characters. - - - `instructions: Optional[str]` - - The system instructions that the assistant uses. The maximum length is 256,000 characters. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `model: str` - - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - - `name: Optional[str]` - - The name of the assistant. The maximum length is 256 characters. - - - `object: Literal["assistant"]` - - The object type, which is always `assistant`. - - - `"assistant"` - - - `tools: List[AssistantTool]` - - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - - - `response_format: Optional[AssistantResponseFormatOption]` - - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - - `Literal["auto"]` - - `auto` is the default value - - - `"auto"` - - - `class ResponseFormatText: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class ResponseFormatJSONObject: …` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `type: Literal["json_object"]` - - The type of response format being defined. Always `json_object`. - - - `"json_object"` - - - `class ResponseFormatJSONSchema: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_schema: JSONSchema` - - Structured Outputs configuration options, including a JSON Schema. - - - `name: str` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `schema: Optional[Dict[str, object]]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - - - `temperature: Optional[float]` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - - `tool_resources: Optional[ToolResources]` - - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - - `file_ids: Optional[List[str]]` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: Optional[ToolResourcesFileSearch]` - - - `vector_store_ids: Optional[List[str]]` - - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - - `top_p: Optional[float]` - - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - We generally recommend altering this or temperature but not both. - -### Example - -```python -import os -from openai import OpenAI - -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -assistant = client.beta.assistants.update( - assistant_id="assistant_id", -) -print(assistant.id) -``` - -#### Response - -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - { - "type": "code_interpreter" - } - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` - -### Example - -```python -from openai import OpenAI -client = OpenAI() - -my_updated_assistant = client.beta.assistants.update( - "asst_abc123", - instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", - name="HR Helper", - tools=[{"type": "file_search"}], - model="gpt-4o" -) - -print(my_updated_assistant) -``` - -#### Response - -```json -{ - "id": "asst_123", - "object": "assistant", - "created_at": 1699009709, - "name": "HR Helper", - "description": null, - "model": "gpt-4o", - "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", - "tools": [ - { - "type": "file_search" - } - ], - "tool_resources": { - "file_search": { - "vector_store_ids": [] - } - }, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" -} -``` - -## Delete assistant - -`beta.assistants.delete(strassistant_id) -> AssistantDeleted` - -**delete** `/assistants/{assistant_id}` - -Delete an assistant. - -### Parameters - -- `assistant_id: str` - -### Returns - -- `class AssistantDeleted: …` - - - `id: str` - - - `deleted: bool` - - - `object: Literal["assistant.deleted"]` - - - `"assistant.deleted"` - -### Example - -```python -import os -from openai import OpenAI - -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -assistant_deleted = client.beta.assistants.delete( - "assistant_id", -) -print(assistant_deleted.id) -``` - -#### Response - -```json -{ - "id": "id", - "deleted": true, - "object": "assistant.deleted" -} -``` - -### Example - -```python -from openai import OpenAI -client = OpenAI() - -response = client.beta.assistants.delete("asst_abc123") -print(response) -``` - -#### Response - -```json -{ - "id": "asst_abc123", - "object": "assistant.deleted", - "deleted": true -} -``` - -## Domain Types - -### Assistant - -- `class Assistant: …` - - Represents an `assistant` that can call the model and use tools. - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the assistant was created. - - - `description: Optional[str]` - - The description of the assistant. The maximum length is 512 characters. - - - `instructions: Optional[str]` - - The system instructions that the assistant uses. The maximum length is 256,000 characters. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `model: str` - - ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. - - - `name: Optional[str]` - - The name of the assistant. The maximum length is 256 characters. - - - `object: Literal["assistant"]` - - The object type, which is always `assistant`. - - - `"assistant"` - - - `tools: List[AssistantTool]` - - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - - - `response_format: Optional[AssistantResponseFormatOption]` - - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - - `Literal["auto"]` - - `auto` is the default value - - - `"auto"` - - - `class ResponseFormatText: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class ResponseFormatJSONObject: …` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `type: Literal["json_object"]` - - The type of response format being defined. Always `json_object`. - - - `"json_object"` - - - `class ResponseFormatJSONSchema: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_schema: JSONSchema` - - Structured Outputs configuration options, including a JSON Schema. - - - `name: str` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `schema: Optional[Dict[str, object]]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - - - `temperature: Optional[float]` - - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - - - `tool_resources: Optional[ToolResources]` - - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - - `file_ids: Optional[List[str]]` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: Optional[ToolResourcesFileSearch]` - - - `vector_store_ids: Optional[List[str]]` - - The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - - `top_p: Optional[float]` - - An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. - - We generally recommend altering this or temperature but not both. - -### Assistant Deleted - -- `class AssistantDeleted: …` - - - `id: str` - - - `deleted: bool` - - - `object: Literal["assistant.deleted"]` - - - `"assistant.deleted"` - -### Assistant Stream Event - -- `AssistantStreamEvent` - - Represents an event emitted when streaming a Run. - - Each event in a server-sent events stream has an `event` and `data` property: - - ``` - event: thread.created - data: {"id": "thread_123", "object": "thread", ...} - ``` - - We emit events whenever a new object is created, transitions to a new state, or is being - streamed in parts (deltas). For example, we emit `thread.run.created` when a new run - is created, `thread.run.completed` when a run completes, and so on. When an Assistant chooses - to create a message during a run, we emit a `thread.message.created event`, a - `thread.message.in_progress` event, many `thread.message.delta` events, and finally a - `thread.message.completed` event. - - We may add additional events over time, so we recommend handling unknown events gracefully - in your code. See the [Assistants API quickstart](https://platform.openai.com/docs/assistants/overview) to learn how to - integrate the Assistants API with streaming. - - - `class ThreadCreated: …` - - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. - - - `data: Thread` - - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the thread was created. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `object: Literal["thread"]` - - The object type, which is always `thread`. - - - `"thread"` - - - `tool_resources: Optional[ToolResources]` - - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - - `file_ids: Optional[List[str]]` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: Optional[ToolResourcesFileSearch]` - - - `vector_store_ids: Optional[List[str]]` - - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - - `event: Literal["thread.created"]` - - - `"thread.created"` - - - `enabled: Optional[bool]` - - Whether to enable input audio transcription. - - - `class ThreadRunCreated: …` - - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `assistant_id: str` - - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - - `cancelled_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run was cancelled. - - - `completed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run was completed. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the run was created. - - - `expires_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run will expire. - - - `failed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run failed. - - - `incomplete_details: Optional[IncompleteDetails]` - - Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - - `"max_completion_tokens"` - - - `"max_prompt_tokens"` - - - `instructions: str` - - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - - `last_error: Optional[LastError]` - - The last error associated with this run. Will be `null` if there are no errors. - - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - - `"server_error"` - - - `"rate_limit_exceeded"` - - - `"invalid_prompt"` - - - `message: str` - - A human-readable description of the error. - - - `max_completion_tokens: Optional[int]` - - The maximum number of completion tokens specified to have been used over the course of the run. - - - `max_prompt_tokens: Optional[int]` - - The maximum number of prompt tokens specified to have been used over the course of the run. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `model: str` - - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - - `object: Literal["thread.run"]` - - The object type, which is always `thread.run`. - - - `"thread.run"` - - - `parallel_tool_calls: bool` - - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - - `required_action: Optional[RequiredAction]` - - Details on the action required to continue the run. Will be `null` if no action is required. - - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - - Details on the tool outputs needed for this run to continue. - - - `tool_calls: List[RequiredActionFunctionToolCall]` - - A list of the relevant tool calls. - - - `id: str` - - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - - `function: Function` - - The function definition. - - - `arguments: str` - - The arguments that the model expects you to pass to the function. - - - `name: str` - - The name of the function. - - - `type: Literal["function"]` - - The type of tool call the output is required for. For now, this is always `function`. - - - `"function"` - - - `type: Literal["submit_tool_outputs"]` - - For now, this is always `submit_tool_outputs`. - - - `"submit_tool_outputs"` - - - `response_format: Optional[AssistantResponseFormatOption]` - - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - - `Literal["auto"]` - - `auto` is the default value - - - `"auto"` - - - `class ResponseFormatText: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class ResponseFormatJSONObject: …` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `type: Literal["json_object"]` - - The type of response format being defined. Always `json_object`. - - - `"json_object"` - - - `class ResponseFormatJSONSchema: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_schema: JSONSchema` - - Structured Outputs configuration options, including a JSON Schema. - - - `name: str` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `schema: Optional[Dict[str, object]]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - - - `started_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run was started. - - - `status: RunStatus` - - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - - `"queued"` - - - `"in_progress"` - - - `"requires_action"` - - - `"cancelling"` - - - `"cancelled"` - - - `"failed"` - - - `"completed"` - - - `"incomplete"` - - - `"expired"` - - - `thread_id: str` - - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - - `tool_choice: Optional[AssistantToolChoiceOption]` - - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - - `Literal["none", "auto", "required"]` - - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - - `"none"` - - - `"auto"` - - - `"required"` - - - `class AssistantToolChoice: …` - - Specifies a tool the model should use. Use to force the model to call a specific tool. - - - `type: Literal["function", "code_interpreter", "file_search"]` - - The type of the tool. If type is `function`, the function name must be set - - - `"function"` - - - `"code_interpreter"` - - - `"file_search"` - - - `function: Optional[AssistantToolChoiceFunction]` - - - `name: str` - - The name of the function to call. - - - `tools: List[AssistantTool]` - - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - - - `truncation_strategy: Optional[TruncationStrategy]` - - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - - `type: Literal["auto", "last_messages"]` - - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - - `"auto"` - - - `"last_messages"` - - - `last_messages: Optional[int]` - - The number of most recent messages from the thread when constructing the context for the run. - - - `usage: Optional[Usage]` - - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - - `completion_tokens: int` - - Number of completion tokens used over the course of the run. - - - `prompt_tokens: int` - - Number of prompt tokens used over the course of the run. - - - `total_tokens: int` - - Total number of tokens used (prompt + completion). - - - `temperature: Optional[float]` - - The sampling temperature used for this run. If not set, defaults to 1. - - - `top_p: Optional[float]` - - The nucleus sampling value used for this run. If not set, defaults to 1. - - - `event: Literal["thread.run.created"]` - - - `"thread.run.created"` - - - `class ThreadRunQueued: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.queued"]` - - - `"thread.run.queued"` - - - `class ThreadRunInProgress: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.in_progress"]` - - - `"thread.run.in_progress"` - - - `class ThreadRunRequiresAction: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.requires_action"]` - - - `"thread.run.requires_action"` - - - `class ThreadRunCompleted: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.completed"]` - - - `"thread.run.completed"` - - - `class ThreadRunIncomplete: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.incomplete"]` - - - `"thread.run.incomplete"` - - - `class ThreadRunFailed: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.failed"]` - - - `"thread.run.failed"` - - - `class ThreadRunCancelling: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.cancelling"]` - - - `"thread.run.cancelling"` - - - `class ThreadRunCancelled: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.cancelled"]` - - - `"thread.run.cancelled"` - - - `class ThreadRunExpired: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.expired"]` - - - `"thread.run.expired"` - - - `class ThreadRunStepCreated: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `id: str` - - The identifier of the run step, which can be referenced in API endpoints. - - - `assistant_id: str` - - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - - `cancelled_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run step was cancelled. - - - `completed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run step completed. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the run step was created. - - - `expired_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - - `failed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run step failed. - - - `last_error: Optional[LastError]` - - The last error associated with this run step. Will be `null` if there are no errors. - - - `code: Literal["server_error", "rate_limit_exceeded"]` - - One of `server_error` or `rate_limit_exceeded`. - - - `"server_error"` - - - `"rate_limit_exceeded"` - - - `message: str` - - A human-readable description of the error. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `object: Literal["thread.run.step"]` - - The object type, which is always `thread.run.step`. - - - `"thread.run.step"` - - - `run_id: str` - - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - - `status: Literal["in_progress", "cancelled", "failed", 2 more]` - - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - - `"in_progress"` - - - `"cancelled"` - - - `"failed"` - - - `"completed"` - - - `"expired"` - - - `step_details: StepDetails` - - The details of the run step. - - - `class MessageCreationStepDetails: …` - - Details of the message creation by the run step. - - - `message_creation: MessageCreation` - - - `message_id: str` - - The ID of the message that was created by this run step. - - - `type: Literal["message_creation"]` - - Always `message_creation`. - - - `"message_creation"` - - - `class ToolCallsStepDetails: …` - - Details of the tool call. - - - `tool_calls: List[ToolCall]` - - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterToolCall: …` - - Details of the Code Interpreter tool call the run step was involved in. - - - `id: str` - - The ID of the tool call. - - - `code_interpreter: CodeInterpreter` - - The Code Interpreter tool call definition. - - - `input: str` - - The input to the Code Interpreter tool call. - - - `outputs: List[CodeInterpreterOutput]` - - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - - `class CodeInterpreterOutputLogs: …` - - Text output from the Code Interpreter tool call as part of a run step. - - - `logs: str` - - The text output from the Code Interpreter tool call. - - - `type: Literal["logs"]` - - Always `logs`. - - - `"logs"` - - - `class CodeInterpreterOutputImage: …` - - - `image: CodeInterpreterOutputImageImage` - - - `file_id: str` - - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - - `type: Literal["image"]` - - Always `image`. - - - `"image"` - - - `type: Literal["code_interpreter"]` - - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - - `"code_interpreter"` - - - `class FileSearchToolCall: …` - - - `id: str` - - The ID of the tool call object. - - - `file_search: FileSearch` - - For now, this is always going to be an empty object. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. - - - `ranker: Literal["auto", "default_2024_08_21"]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `results: Optional[List[FileSearchResult]]` - - The results of the file search. - - - `file_id: str` - - The ID of the file that result was found in. - - - `file_name: str` - - The name of the file that result was found in. - - - `score: float` - - The score of the result. All values must be a floating point number between 0 and 1. - - - `content: Optional[List[FileSearchResultContent]]` - - The content of the result that was found. The content is only included if requested via the include query parameter. - - - `text: Optional[str]` - - The text content of the file. - - - `type: Optional[Literal["text"]]` - - The type of the content. - - - `"text"` - - - `type: Literal["file_search"]` - - The type of tool call. This is always going to be `file_search` for this type of tool call. - - - `"file_search"` - - - `class FunctionToolCall: …` - - - `id: str` - - The ID of the tool call object. - - - `function: Function` - - The definition of the function that was called. - - - `arguments: str` - - The arguments passed to the function. - - - `name: str` - - The name of the function. - - - `output: Optional[str]` - - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - - `type: Literal["function"]` - - The type of tool call. This is always going to be `function` for this type of tool call. - - - `"function"` - - - `type: Literal["tool_calls"]` - - Always `tool_calls`. - - - `"tool_calls"` - - - `thread_id: str` - - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - - `type: Literal["message_creation", "tool_calls"]` - - The type of run step, which can be either `message_creation` or `tool_calls`. - - - `"message_creation"` - - - `"tool_calls"` - - - `usage: Optional[Usage]` - - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - - `completion_tokens: int` - - Number of completion tokens used over the course of the run step. - - - `prompt_tokens: int` - - Number of prompt tokens used over the course of the run step. - - - `total_tokens: int` - - Total number of tokens used (prompt + completion). - - - `event: Literal["thread.run.step.created"]` - - - `"thread.run.step.created"` - - - `class ThreadRunStepInProgress: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.in_progress"]` - - - `"thread.run.step.in_progress"` - - - `class ThreadRunStepDelta: …` - - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. - - - `data: RunStepDeltaEvent` - - Represents a run step delta i.e. any changed fields on a run step during streaming. - - - `id: str` - - The identifier of the run step, which can be referenced in API endpoints. - - - `delta: RunStepDelta` - - The delta containing the fields that have changed on the run step. - - - `step_details: Optional[StepDetails]` - - The details of the run step. - - - `class RunStepDeltaMessageDelta: …` - - Details of the message creation by the run step. - - - `type: Literal["message_creation"]` - - Always `message_creation`. - - - `"message_creation"` - - - `message_creation: Optional[MessageCreation]` - - - `message_id: Optional[str]` - - The ID of the message that was created by this run step. - - - `class ToolCallDeltaObject: …` - - Details of the tool call. - - - `type: Literal["tool_calls"]` - - Always `tool_calls`. - - - `"tool_calls"` - - - `tool_calls: Optional[List[ToolCallDelta]]` - - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterToolCallDelta: …` - - Details of the Code Interpreter tool call the run step was involved in. - - - `index: int` - - The index of the tool call in the tool calls array. - - - `type: Literal["code_interpreter"]` - - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - - `"code_interpreter"` - - - `id: Optional[str]` - - The ID of the tool call. - - - `code_interpreter: Optional[CodeInterpreter]` - - The Code Interpreter tool call definition. - - - `input: Optional[str]` - - The input to the Code Interpreter tool call. - - - `outputs: Optional[List[CodeInterpreterOutput]]` - - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - - `class CodeInterpreterLogs: …` - - Text output from the Code Interpreter tool call as part of a run step. - - - `index: int` - - The index of the output in the outputs array. - - - `type: Literal["logs"]` - - Always `logs`. - - - `"logs"` - - - `logs: Optional[str]` - - The text output from the Code Interpreter tool call. - - - `class CodeInterpreterOutputImage: …` - - - `index: int` - - The index of the output in the outputs array. - - - `type: Literal["image"]` - - Always `image`. - - - `"image"` - - - `image: Optional[Image]` - - - `file_id: Optional[str]` - - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - - `class FileSearchToolCallDelta: …` - - - `file_search: object` - - For now, this is always going to be an empty object. - - - `index: int` - - The index of the tool call in the tool calls array. - - - `type: Literal["file_search"]` - - The type of tool call. This is always going to be `file_search` for this type of tool call. - - - `"file_search"` - - - `id: Optional[str]` - - The ID of the tool call object. - - - `class FunctionToolCallDelta: …` - - - `index: int` - - The index of the tool call in the tool calls array. - - - `type: Literal["function"]` - - The type of tool call. This is always going to be `function` for this type of tool call. - - - `"function"` - - - `id: Optional[str]` - - The ID of the tool call object. - - - `function: Optional[Function]` - - The definition of the function that was called. - - - `arguments: Optional[str]` - - The arguments passed to the function. - - - `name: Optional[str]` - - The name of the function. - - - `output: Optional[str]` - - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - - `object: Literal["thread.run.step.delta"]` - - The object type, which is always `thread.run.step.delta`. - - - `"thread.run.step.delta"` - - - `event: Literal["thread.run.step.delta"]` - - - `"thread.run.step.delta"` - - - `class ThreadRunStepCompleted: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.completed"]` - - - `"thread.run.step.completed"` - - - `class ThreadRunStepFailed: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.failed"]` - - - `"thread.run.step.failed"` - - - `class ThreadRunStepCancelled: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.cancelled"]` - - - `"thread.run.step.cancelled"` - - - `class ThreadRunStepExpired: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.expired"]` - - - `"thread.run.step.expired"` - - - `class ThreadMessageCreated: …` - - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - - - `data: Message` - - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `assistant_id: Optional[str]` - - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - - `attachments: Optional[List[Attachment]]` - - A list of files attached to the message, and the tools they were added to. - - - `file_id: Optional[str]` - - The ID of the file to attach to the message. - - - `tools: Optional[List[AttachmentTool]]` - - The tools to add this file to. - - - `class CodeInterpreterTool: …` - - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `completed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the message was completed. - - - `content: List[MessageContent]` - - The content of the message in array of text and/or images. - - - `class ImageFileContentBlock: …` - - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - - `image_file: ImageFile` - - - `file_id: str` - - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - - `detail: Optional[Literal["auto", "low", "high"]]` - - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `type: Literal["image_file"]` - - Always `image_file`. - - - `"image_file"` - - - `class ImageURLContentBlock: …` - - References an image URL in the content of a message. - - - `image_url: ImageURL` - - - `url: str` - - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - - `detail: Optional[Literal["auto", "low", "high"]]` - - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - - `"auto"` - - - `"low"` - - - `"high"` - - - `type: Literal["image_url"]` - - The type of the content part. - - - `"image_url"` - - - `class TextContentBlock: …` - - The text content that is part of a message. - - - `text: Text` - - - `annotations: List[Annotation]` - - - `class FileCitationAnnotation: …` - - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - - `end_index: int` - - - `file_citation: FileCitation` - - - `file_id: str` - - The ID of the specific File the citation is from. - - - `start_index: int` - - - `text: str` - - The text in the message content that needs to be replaced. - - - `type: Literal["file_citation"]` - - Always `file_citation`. - - - `"file_citation"` - - - `class FilePathAnnotation: …` - - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - - `end_index: int` - - - `file_path: FilePath` - - - `file_id: str` - - The ID of the file that was generated. - - - `start_index: int` - - - `text: str` - - The text in the message content that needs to be replaced. - - - `type: Literal["file_path"]` - - Always `file_path`. - - - `"file_path"` - - - `value: str` - - The data that makes up the text. - - - `type: Literal["text"]` - - Always `text`. - - - `"text"` - - - `class RefusalContentBlock: …` - - The refusal content generated by the assistant. - - - `refusal: str` - - - `type: Literal["refusal"]` - - Always `refusal`. - - - `"refusal"` - - - `created_at: int` - - The Unix timestamp (in seconds) for when the message was created. - - - `incomplete_at: Optional[int]` - - The Unix timestamp (in seconds) for when the message was marked as incomplete. - - - `incomplete_details: Optional[IncompleteDetails]` - - On an incomplete message, details about why the message is incomplete. - - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` - - The reason the message is incomplete. - - - `"content_filter"` - - - `"max_tokens"` - - - `"run_cancelled"` - - - `"run_expired"` - - - `"run_failed"` - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `object: Literal["thread.message"]` - - The object type, which is always `thread.message`. - - - `"thread.message"` - - - `role: Literal["user", "assistant"]` - - The entity that produced the message. One of `user` or `assistant`. - - - `"user"` - - - `"assistant"` - - - `run_id: Optional[str]` - - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - - `status: Literal["in_progress", "incomplete", "completed"]` - - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - - `"in_progress"` - - - `"incomplete"` - - - `"completed"` - - - `thread_id: str` - - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - - `event: Literal["thread.message.created"]` - - - `"thread.message.created"` - - - `class ThreadMessageInProgress: …` - - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. - - - `data: Message` - - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.message.in_progress"]` - - - `"thread.message.in_progress"` - - - `class ThreadMessageDelta: …` - - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. - - - `data: MessageDeltaEvent` - - Represents a message delta i.e. any changed fields on a message during streaming. - - - `id: str` - - The identifier of the message, which can be referenced in API endpoints. - - - `delta: MessageDelta` - - The delta containing the fields that have changed on the Message. - - - `content: Optional[List[MessageContentDelta]]` - - The content of the message in array of text and/or images. - - - `class ImageFileDeltaBlock: …` - - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - - `index: int` - - The index of the content part in the message. - - - `type: Literal["image_file"]` - - Always `image_file`. - - - `"image_file"` - - - `image_file: Optional[ImageFileDelta]` - - - `detail: Optional[Literal["auto", "low", "high"]]` - - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_id: Optional[str]` - - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - - `class TextDeltaBlock: …` - - The text content that is part of a message. - - - `index: int` - - The index of the content part in the message. - - - `type: Literal["text"]` - - Always `text`. - - - `"text"` - - - `text: Optional[TextDelta]` - - - `annotations: Optional[List[AnnotationDelta]]` - - - `class FileCitationDeltaAnnotation: …` - - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - - `index: int` - - The index of the annotation in the text content part. - - - `type: Literal["file_citation"]` - - Always `file_citation`. - - - `"file_citation"` - - - `end_index: Optional[int]` - - - `file_citation: Optional[FileCitation]` - - - `file_id: Optional[str]` - - The ID of the specific File the citation is from. - - - `quote: Optional[str]` - - The specific quote in the file. - - - `start_index: Optional[int]` - - - `text: Optional[str]` - - The text in the message content that needs to be replaced. - - - `class FilePathDeltaAnnotation: …` - - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - - `index: int` - - The index of the annotation in the text content part. - - - `type: Literal["file_path"]` - - Always `file_path`. - - - `"file_path"` - - - `end_index: Optional[int]` - - - `file_path: Optional[FilePath]` - - - `file_id: Optional[str]` - - The ID of the file that was generated. - - - `start_index: Optional[int]` - - - `text: Optional[str]` - - The text in the message content that needs to be replaced. - - - `value: Optional[str]` - - The data that makes up the text. - - - `class RefusalDeltaBlock: …` - - The refusal content that is part of a message. - - - `index: int` - - The index of the refusal part in the message. - - - `type: Literal["refusal"]` - - Always `refusal`. - - - `"refusal"` - - - `refusal: Optional[str]` - - - `class ImageURLDeltaBlock: …` - - References an image URL in the content of a message. - - - `index: int` - - The index of the content part in the message. - - - `type: Literal["image_url"]` - - Always `image_url`. - - - `"image_url"` - - - `image_url: Optional[ImageURLDelta]` - - - `detail: Optional[Literal["auto", "low", "high"]]` - - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `url: Optional[str]` - - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - - `role: Optional[Literal["user", "assistant"]]` - - The entity that produced the message. One of `user` or `assistant`. - - - `"user"` - - - `"assistant"` - - - `object: Literal["thread.message.delta"]` - - The object type, which is always `thread.message.delta`. - - - `"thread.message.delta"` - - - `event: Literal["thread.message.delta"]` - - - `"thread.message.delta"` - - - `class ThreadMessageCompleted: …` - - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. - - - `data: Message` - - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.message.completed"]` - - - `"thread.message.completed"` - - - `class ThreadMessageIncomplete: …` - - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. - - - `data: Message` - - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.message.incomplete"]` - - - `"thread.message.incomplete"` - - - `class ErrorEvent: …` - - Occurs when an [error](https://platform.openai.com/docs/guides/error-codes#api-errors) occurs. This can happen due to an internal server error or a timeout. - - - `data: ErrorObject` - - - `code: Optional[str]` - - - `message: str` - - - `param: Optional[str]` - - - `type: str` - - - `event: Literal["error"]` - - - `"error"` - -### Assistant Tool - -- `AssistantTool` - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - -### Code Interpreter Tool - -- `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - -### File Search Tool - -- `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - -### Function Tool - -- `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - -### Message Stream Event - -- `MessageStreamEvent` - - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - - - `class ThreadMessageCreated: …` - - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is created. - - - `data: Message` - - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `assistant_id: Optional[str]` - - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. - - - `attachments: Optional[List[Attachment]]` - - A list of files attached to the message, and the tools they were added to. - - - `file_id: Optional[str]` - - The ID of the file to attach to the message. - - - `tools: Optional[List[AttachmentTool]]` - - The tools to add this file to. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `completed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the message was completed. - - - `content: List[MessageContent]` - - The content of the message in array of text and/or images. - - - `class ImageFileContentBlock: …` - - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - - `image_file: ImageFile` - - - `file_id: str` - - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - - `detail: Optional[Literal["auto", "low", "high"]]` - - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `type: Literal["image_file"]` - - Always `image_file`. - - - `"image_file"` - - - `class ImageURLContentBlock: …` - - References an image URL in the content of a message. - - - `image_url: ImageURL` - - - `url: str` - - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - - `detail: Optional[Literal["auto", "low", "high"]]` - - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - - `"auto"` - - - `"low"` - - - `"high"` - - - `type: Literal["image_url"]` - - The type of the content part. - - - `"image_url"` - - - `class TextContentBlock: …` - - The text content that is part of a message. - - - `text: Text` - - - `annotations: List[Annotation]` - - - `class FileCitationAnnotation: …` - - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - - `end_index: int` - - - `file_citation: FileCitation` - - - `file_id: str` - - The ID of the specific File the citation is from. - - - `start_index: int` - - - `text: str` - - The text in the message content that needs to be replaced. - - - `type: Literal["file_citation"]` - - Always `file_citation`. - - - `"file_citation"` - - - `class FilePathAnnotation: …` - - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - - `end_index: int` - - - `file_path: FilePath` - - - `file_id: str` - - The ID of the file that was generated. - - - `start_index: int` - - - `text: str` - - The text in the message content that needs to be replaced. - - - `type: Literal["file_path"]` - - Always `file_path`. - - - `"file_path"` - - - `value: str` - - The data that makes up the text. - - - `type: Literal["text"]` - - Always `text`. - - - `"text"` - - - `class RefusalContentBlock: …` - - The refusal content generated by the assistant. - - - `refusal: str` - - - `type: Literal["refusal"]` - - Always `refusal`. - - - `"refusal"` - - - `created_at: int` - - The Unix timestamp (in seconds) for when the message was created. - - - `incomplete_at: Optional[int]` - - The Unix timestamp (in seconds) for when the message was marked as incomplete. - - - `incomplete_details: Optional[IncompleteDetails]` - - On an incomplete message, details about why the message is incomplete. - - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` - - The reason the message is incomplete. - - - `"content_filter"` - - - `"max_tokens"` - - - `"run_cancelled"` - - - `"run_expired"` - - - `"run_failed"` - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `object: Literal["thread.message"]` - - The object type, which is always `thread.message`. - - - `"thread.message"` - - - `role: Literal["user", "assistant"]` - - The entity that produced the message. One of `user` or `assistant`. - - - `"user"` - - - `"assistant"` - - - `run_id: Optional[str]` - - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - - `status: Literal["in_progress", "incomplete", "completed"]` - - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - - `"in_progress"` - - - `"incomplete"` - - - `"completed"` - - - `thread_id: str` - - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. - - - `event: Literal["thread.message.created"]` - - - `"thread.message.created"` - - - `class ThreadMessageInProgress: …` - - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) moves to an `in_progress` state. - - - `data: Message` - - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.message.in_progress"]` - - - `"thread.message.in_progress"` - - - `class ThreadMessageDelta: …` - - Occurs when parts of a [Message](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. - - - `data: MessageDeltaEvent` - - Represents a message delta i.e. any changed fields on a message during streaming. - - - `id: str` - - The identifier of the message, which can be referenced in API endpoints. - - - `delta: MessageDelta` - - The delta containing the fields that have changed on the Message. - - - `content: Optional[List[MessageContentDelta]]` - - The content of the message in array of text and/or images. - - - `class ImageFileDeltaBlock: …` - - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - - `index: int` - - The index of the content part in the message. - - - `type: Literal["image_file"]` - - Always `image_file`. - - - `"image_file"` - - - `image_file: Optional[ImageFileDelta]` - - - `detail: Optional[Literal["auto", "low", "high"]]` - - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `file_id: Optional[str]` - - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - - `class TextDeltaBlock: …` - - The text content that is part of a message. - - - `index: int` - - The index of the content part in the message. - - - `type: Literal["text"]` - - Always `text`. - - - `"text"` - - - `text: Optional[TextDelta]` - - - `annotations: Optional[List[AnnotationDelta]]` - - - `class FileCitationDeltaAnnotation: …` - - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - - `index: int` - - The index of the annotation in the text content part. - - - `type: Literal["file_citation"]` - - Always `file_citation`. - - - `"file_citation"` - - - `end_index: Optional[int]` - - - `file_citation: Optional[FileCitation]` - - - `file_id: Optional[str]` - - The ID of the specific File the citation is from. - - - `quote: Optional[str]` - - The specific quote in the file. - - - `start_index: Optional[int]` - - - `text: Optional[str]` - - The text in the message content that needs to be replaced. - - - `class FilePathDeltaAnnotation: …` - - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - - `index: int` - - The index of the annotation in the text content part. - - - `type: Literal["file_path"]` - - Always `file_path`. - - - `"file_path"` - - - `end_index: Optional[int]` - - - `file_path: Optional[FilePath]` - - - `file_id: Optional[str]` - - The ID of the file that was generated. - - - `start_index: Optional[int]` - - - `text: Optional[str]` - - The text in the message content that needs to be replaced. - - - `value: Optional[str]` - - The data that makes up the text. - - - `class RefusalDeltaBlock: …` - - The refusal content that is part of a message. - - - `index: int` - - The index of the refusal part in the message. - - - `type: Literal["refusal"]` - - Always `refusal`. - - - `"refusal"` - - - `refusal: Optional[str]` - - - `class ImageURLDeltaBlock: …` - - References an image URL in the content of a message. - - - `index: int` - - The index of the content part in the message. - - - `type: Literal["image_url"]` - - Always `image_url`. - - - `"image_url"` - - - `image_url: Optional[ImageURLDelta]` - - - `detail: Optional[Literal["auto", "low", "high"]]` - - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `url: Optional[str]` - - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - - `role: Optional[Literal["user", "assistant"]]` - - The entity that produced the message. One of `user` or `assistant`. - - - `"user"` - - - `"assistant"` - - - `object: Literal["thread.message.delta"]` - - The object type, which is always `thread.message.delta`. - - - `"thread.message.delta"` - - - `event: Literal["thread.message.delta"]` - - - `"thread.message.delta"` - - - `class ThreadMessageCompleted: …` - - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) is completed. - - - `data: Message` - - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.message.completed"]` - - - `"thread.message.completed"` - - - `class ThreadMessageIncomplete: …` - - Occurs when a [message](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. - - - `data: Message` - - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.message.incomplete"]` - - - `"thread.message.incomplete"` - -### Run Step Stream Event - -- `RunStepStreamEvent` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - - `class ThreadRunStepCreated: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `id: str` - - The identifier of the run step, which can be referenced in API endpoints. - - - `assistant_id: str` - - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. - - - `cancelled_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run step was cancelled. - - - `completed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run step completed. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the run step was created. - - - `expired_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - - `failed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run step failed. - - - `last_error: Optional[LastError]` - - The last error associated with this run step. Will be `null` if there are no errors. - - - `code: Literal["server_error", "rate_limit_exceeded"]` - - One of `server_error` or `rate_limit_exceeded`. - - - `"server_error"` - - - `"rate_limit_exceeded"` - - - `message: str` - - A human-readable description of the error. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `object: Literal["thread.run.step"]` - - The object type, which is always `thread.run.step`. - - - `"thread.run.step"` - - - `run_id: str` - - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. - - - `status: Literal["in_progress", "cancelled", "failed", 2 more]` - - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - - `"in_progress"` - - - `"cancelled"` - - - `"failed"` - - - `"completed"` - - - `"expired"` - - - `step_details: StepDetails` - - The details of the run step. - - - `class MessageCreationStepDetails: …` - - Details of the message creation by the run step. - - - `message_creation: MessageCreation` - - - `message_id: str` - - The ID of the message that was created by this run step. - - - `type: Literal["message_creation"]` - - Always `message_creation`. - - - `"message_creation"` - - - `class ToolCallsStepDetails: …` - - Details of the tool call. - - - `tool_calls: List[ToolCall]` - - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterToolCall: …` - - Details of the Code Interpreter tool call the run step was involved in. - - - `id: str` - - The ID of the tool call. - - - `code_interpreter: CodeInterpreter` - - The Code Interpreter tool call definition. - - - `input: str` - - The input to the Code Interpreter tool call. - - - `outputs: List[CodeInterpreterOutput]` - - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - - `class CodeInterpreterOutputLogs: …` - - Text output from the Code Interpreter tool call as part of a run step. - - - `logs: str` - - The text output from the Code Interpreter tool call. - - - `type: Literal["logs"]` - - Always `logs`. - - - `"logs"` - - - `class CodeInterpreterOutputImage: …` - - - `image: CodeInterpreterOutputImageImage` - - - `file_id: str` - - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - - `type: Literal["image"]` - - Always `image`. - - - `"image"` - - - `type: Literal["code_interpreter"]` - - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - - `"code_interpreter"` - - - `class FileSearchToolCall: …` - - - `id: str` - - The ID of the tool call object. - - - `file_search: FileSearch` - - For now, this is always going to be an empty object. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. - - - `ranker: Literal["auto", "default_2024_08_21"]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `results: Optional[List[FileSearchResult]]` - - The results of the file search. - - - `file_id: str` - - The ID of the file that result was found in. - - - `file_name: str` - - The name of the file that result was found in. - - - `score: float` - - The score of the result. All values must be a floating point number between 0 and 1. - - - `content: Optional[List[FileSearchResultContent]]` - - The content of the result that was found. The content is only included if requested via the include query parameter. - - - `text: Optional[str]` - - The text content of the file. - - - `type: Optional[Literal["text"]]` - - The type of the content. - - - `"text"` - - - `type: Literal["file_search"]` - - The type of tool call. This is always going to be `file_search` for this type of tool call. - - - `"file_search"` - - - `class FunctionToolCall: …` - - - `id: str` - - The ID of the tool call object. - - - `function: Function` - - The definition of the function that was called. - - - `arguments: str` - - The arguments passed to the function. - - - `name: str` - - The name of the function. - - - `output: Optional[str]` - - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - - `type: Literal["function"]` - - The type of tool call. This is always going to be `function` for this type of tool call. - - - `"function"` - - - `type: Literal["tool_calls"]` - - Always `tool_calls`. - - - `"tool_calls"` - - - `thread_id: str` - - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. - - - `type: Literal["message_creation", "tool_calls"]` - - The type of run step, which can be either `message_creation` or `tool_calls`. - - - `"message_creation"` - - - `"tool_calls"` - - - `usage: Optional[Usage]` - - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - - `completion_tokens: int` - - Number of completion tokens used over the course of the run step. - - - `prompt_tokens: int` - - Number of prompt tokens used over the course of the run step. - - - `total_tokens: int` - - Total number of tokens used (prompt + completion). - - - `event: Literal["thread.run.step.created"]` - - - `"thread.run.step.created"` - - - `class ThreadRunStepInProgress: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.in_progress"]` - - - `"thread.run.step.in_progress"` - - - `class ThreadRunStepDelta: …` - - Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. - - - `data: RunStepDeltaEvent` - - Represents a run step delta i.e. any changed fields on a run step during streaming. - - - `id: str` - - The identifier of the run step, which can be referenced in API endpoints. - - - `delta: RunStepDelta` - - The delta containing the fields that have changed on the run step. - - - `step_details: Optional[StepDetails]` - - The details of the run step. - - - `class RunStepDeltaMessageDelta: …` - - Details of the message creation by the run step. - - - `type: Literal["message_creation"]` - - Always `message_creation`. - - - `"message_creation"` - - - `message_creation: Optional[MessageCreation]` - - - `message_id: Optional[str]` - - The ID of the message that was created by this run step. - - - `class ToolCallDeltaObject: …` - - Details of the tool call. - - - `type: Literal["tool_calls"]` - - Always `tool_calls`. - - - `"tool_calls"` - - - `tool_calls: Optional[List[ToolCallDelta]]` - - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - - `class CodeInterpreterToolCallDelta: …` - - Details of the Code Interpreter tool call the run step was involved in. - - - `index: int` - - The index of the tool call in the tool calls array. - - - `type: Literal["code_interpreter"]` - - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - - `"code_interpreter"` - - - `id: Optional[str]` - - The ID of the tool call. - - - `code_interpreter: Optional[CodeInterpreter]` - - The Code Interpreter tool call definition. - - - `input: Optional[str]` - - The input to the Code Interpreter tool call. - - - `outputs: Optional[List[CodeInterpreterOutput]]` - - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - - `class CodeInterpreterLogs: …` - - Text output from the Code Interpreter tool call as part of a run step. - - - `index: int` - - The index of the output in the outputs array. - - - `type: Literal["logs"]` - - Always `logs`. - - - `"logs"` - - - `logs: Optional[str]` - - The text output from the Code Interpreter tool call. - - - `class CodeInterpreterOutputImage: …` - - - `index: int` - - The index of the output in the outputs array. - - - `type: Literal["image"]` - - Always `image`. - - - `"image"` - - - `image: Optional[Image]` - - - `file_id: Optional[str]` - - The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - - `class FileSearchToolCallDelta: …` - - - `file_search: object` - - For now, this is always going to be an empty object. - - - `index: int` - - The index of the tool call in the tool calls array. - - - `type: Literal["file_search"]` - - The type of tool call. This is always going to be `file_search` for this type of tool call. - - - `"file_search"` - - - `id: Optional[str]` - - The ID of the tool call object. - - - `class FunctionToolCallDelta: …` - - - `index: int` - - The index of the tool call in the tool calls array. - - - `type: Literal["function"]` - - The type of tool call. This is always going to be `function` for this type of tool call. - - - `"function"` - - - `id: Optional[str]` - - The ID of the tool call object. - - - `function: Optional[Function]` - - The definition of the function that was called. - - - `arguments: Optional[str]` - - The arguments passed to the function. - - - `name: Optional[str]` - - The name of the function. - - - `output: Optional[str]` - - The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. - - - `object: Literal["thread.run.step.delta"]` - - The object type, which is always `thread.run.step.delta`. - - - `"thread.run.step.delta"` - - - `event: Literal["thread.run.step.delta"]` - - - `"thread.run.step.delta"` - - - `class ThreadRunStepCompleted: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.completed"]` - - - `"thread.run.step.completed"` - - - `class ThreadRunStepFailed: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.failed"]` - - - `"thread.run.step.failed"` - - - `class ThreadRunStepCancelled: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.cancelled"]` - - - `"thread.run.step.cancelled"` - - - `class ThreadRunStepExpired: …` - - Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. - - - `data: RunStep` - - Represents a step in execution of a run. - - - `event: Literal["thread.run.step.expired"]` - - - `"thread.run.step.expired"` - -### Run Stream Event - -- `RunStreamEvent` - - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - - - `class ThreadRunCreated: …` - - Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `assistant_id: str` - - The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. - - - `cancelled_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run was cancelled. - - - `completed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run was completed. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the run was created. - - - `expires_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run will expire. - - - `failed_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run failed. - - - `incomplete_details: Optional[IncompleteDetails]` - - Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - - `reason: Optional[Literal["max_completion_tokens", "max_prompt_tokens"]]` - - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - - `"max_completion_tokens"` - - - `"max_prompt_tokens"` - - - `instructions: str` - - The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - - `last_error: Optional[LastError]` - - The last error associated with this run. Will be `null` if there are no errors. - - - `code: Literal["server_error", "rate_limit_exceeded", "invalid_prompt"]` - - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - - `"server_error"` - - - `"rate_limit_exceeded"` - - - `"invalid_prompt"` - - - `message: str` - - A human-readable description of the error. - - - `max_completion_tokens: Optional[int]` - - The maximum number of completion tokens specified to have been used over the course of the run. - - - `max_prompt_tokens: Optional[int]` - - The maximum number of prompt tokens specified to have been used over the course of the run. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `model: str` - - The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - - `object: Literal["thread.run"]` - - The object type, which is always `thread.run`. - - - `"thread.run"` - - - `parallel_tool_calls: bool` - - Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - - `required_action: Optional[RequiredAction]` - - Details on the action required to continue the run. Will be `null` if no action is required. - - - `submit_tool_outputs: RequiredActionSubmitToolOutputs` - - Details on the tool outputs needed for this run to continue. - - - `tool_calls: List[RequiredActionFunctionToolCall]` - - A list of the relevant tool calls. - - - `id: str` - - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. - - - `function: Function` - - The function definition. - - - `arguments: str` - - The arguments that the model expects you to pass to the function. - - - `name: str` - - The name of the function. - - - `type: Literal["function"]` - - The type of tool call the output is required for. For now, this is always `function`. - - - `"function"` - - - `type: Literal["submit_tool_outputs"]` - - For now, this is always `submit_tool_outputs`. - - - `"submit_tool_outputs"` - - - `response_format: Optional[AssistantResponseFormatOption]` - - Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - - `Literal["auto"]` - - `auto` is the default value - - - `"auto"` - - - `class ResponseFormatText: …` - - Default response format. Used to generate text responses. - - - `type: Literal["text"]` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `class ResponseFormatJSONObject: …` - - JSON object response format. An older method of generating JSON responses. - Using `json_schema` is recommended for models that support it. Note that the - model will not generate JSON without a system or user message instructing it - to do so. - - - `type: Literal["json_object"]` - - The type of response format being defined. Always `json_object`. - - - `"json_object"` - - - `class ResponseFormatJSONSchema: …` - - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs). - - - `json_schema: JSONSchema` - - Structured Outputs configuration options, including a JSON Schema. - - - `name: str` - - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the response format is for, used by the model to - determine how to respond in the format. - - - `schema: Optional[Dict[str, object]]` - - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://platform.openai.com/docs/guides/structured-outputs). - - - `type: Literal["json_schema"]` - - The type of response format being defined. Always `json_schema`. - - - `"json_schema"` - - - `started_at: Optional[int]` - - The Unix timestamp (in seconds) for when the run was started. - - - `status: RunStatus` - - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - - `"queued"` - - - `"in_progress"` - - - `"requires_action"` - - - `"cancelling"` - - - `"cancelled"` - - - `"failed"` - - - `"completed"` - - - `"incomplete"` - - - `"expired"` - - - `thread_id: str` - - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. - - - `tool_choice: Optional[AssistantToolChoiceOption]` - - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - - `Literal["none", "auto", "required"]` - - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - - `"none"` - - - `"auto"` - - - `"required"` - - - `class AssistantToolChoice: …` - - Specifies a tool the model should use. Use to force the model to call a specific tool. - - - `type: Literal["function", "code_interpreter", "file_search"]` - - The type of the tool. If type is `function`, the function name must be set - - - `"function"` - - - `"code_interpreter"` - - - `"file_search"` - - - `function: Optional[AssistantToolChoiceFunction]` - - - `name: str` - - The name of the function to call. - - - `tools: List[AssistantTool]` - - The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - - `class CodeInterpreterTool: …` - - - `type: Literal["code_interpreter"]` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - - `class FileSearchTool: …` - - - `type: Literal["file_search"]` - - The type of tool being defined: `file_search` - - - `"file_search"` - - - `file_search: Optional[FileSearch]` - - Overrides for the file search tool. - - - `max_num_results: Optional[int]` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `ranking_options: Optional[FileSearchRankingOptions]` - - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `score_threshold: float` - - The score threshold for the file search. All values must be a floating point number between 0 and 1. - - - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` - - The ranker to use for the file search. If not specified will use the `auto` ranker. - - - `"auto"` - - - `"default_2024_08_21"` - - - `class FunctionTool: …` - - - `function: FunctionDefinition` - - - `name: str` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: Optional[str]` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: Optional[FunctionParameters]` - - The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - Omitting `parameters` defines a function with an empty parameter list. - - - `strict: Optional[bool]` - - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). - - - `type: Literal["function"]` - - The type of tool being defined: `function` - - - `"function"` - - - `truncation_strategy: Optional[TruncationStrategy]` - - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - - `type: Literal["auto", "last_messages"]` - - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - - `"auto"` - - - `"last_messages"` - - - `last_messages: Optional[int]` - - The number of most recent messages from the thread when constructing the context for the run. - - - `usage: Optional[Usage]` - - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - - `completion_tokens: int` - - Number of completion tokens used over the course of the run. - - - `prompt_tokens: int` - - Number of prompt tokens used over the course of the run. - - - `total_tokens: int` - - Total number of tokens used (prompt + completion). - - - `temperature: Optional[float]` - - The sampling temperature used for this run. If not set, defaults to 1. - - - `top_p: Optional[float]` - - The nucleus sampling value used for this run. If not set, defaults to 1. - - - `event: Literal["thread.run.created"]` - - - `"thread.run.created"` - - - `class ThreadRunQueued: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.queued"]` - - - `"thread.run.queued"` - - - `class ThreadRunInProgress: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.in_progress"]` - - - `"thread.run.in_progress"` - - - `class ThreadRunRequiresAction: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.requires_action"]` - - - `"thread.run.requires_action"` - - - `class ThreadRunCompleted: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.completed"]` - - - `"thread.run.completed"` - - - `class ThreadRunIncomplete: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.incomplete"]` - - - `"thread.run.incomplete"` - - - `class ThreadRunFailed: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.failed"]` - - - `"thread.run.failed"` - - - `class ThreadRunCancelling: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.cancelling"]` - - - `"thread.run.cancelling"` - - - `class ThreadRunCancelled: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.cancelled"]` - - - `"thread.run.cancelled"` - - - `class ThreadRunExpired: …` - - Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. - - - `data: Run` - - Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). - - - `event: Literal["thread.run.expired"]` - - - `"thread.run.expired"` - -### Thread Stream Event - -- `class ThreadStreamEvent: …` - - Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. - - - `data: Thread` - - Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). - - - `id: str` - - The identifier, which can be referenced in API endpoints. - - - `created_at: int` - - The Unix timestamp (in seconds) for when the thread was created. - - - `metadata: Optional[Metadata]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `object: Literal["thread"]` - - The object type, which is always `thread`. - - - `"thread"` - - - `tool_resources: Optional[ToolResources]` - - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - - `code_interpreter: Optional[ToolResourcesCodeInterpreter]` - - - `file_ids: Optional[List[str]]` - - A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - - `file_search: Optional[ToolResourcesFileSearch]` - - - `vector_store_ids: Optional[List[str]]` - - The [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - - `event: Literal["thread.created"]` - - - `"thread.created"` - - - `enabled: Optional[bool]` - - Whether to enable input audio transcription.